Skip to main content

Import Targets

POST 
/targets/upload/

The upload functionality allows the automatic creation of new targets from multiple file formats (.yaml, .csv, .json).

And one can optionally add scheduled scan data when uploading target data.

The following are the required internal data structures.

CSV data​

The fields about scheduled scan data can be left empty if not necessary.

"name","url","scan_profile","scheduledscan_datetime","scheduledscan_recurrence","labels"
"My target","https://mytarget.url.com","Normal","2022-12-30T12:34:56.224739","m","['label1', 'label2']"
"My other target","https://www.mytargetsite2.com","Normal","","","['label3', 'label2']"

YAML data​

- name: My target
    site:
        name: My target site
        desc: My target site description
        url: https://mytarget.url.com
        # optional site fields
        form_login_url: https://mytarget.url.com/login
        form_login_check_pattern: ""
        form_login: []
        headers: []
        cookies: []
        whitelist: []
    scan_profile: normal
    type: single
    # optional target fields
    report_type: default
    # optional scheduled_scan data
    scheduled_scan:
        date_time: "2022-12-30T12:34:56.224739"
        recurrence: "d"
        timezome: "Europe/Madrid"

JSON data​

Data format with nested ScheduledScan data:

[
    {
        "name": "My target",
        "site": {
            "name": "My target site",
            "desc": "My target description",
            "url": "https://mytarget.url.com",
            # optional site fields
            "form_login_url": "https://mytarget.url.com/login,
            "form_login_check_pattern": "",
            "form_login": [],
            "headers": [],
            "cookies": [],
            "whitelist": []
        },
        "scan_profile": "Normal",
        // optional scheduled_scan data
        "scheduled_scan": {
            "date_time": "2022-12-30T12:34:56.224739",
            "recurrence": "d",
            "timezone": "Europe/Madrid"
        }
    }
]

Data format with flat ScheduledScan data:

[
    {
        "name": "My target",
        "site": {
            "name": "My target site",
            "desc": "My target description",
            "url": "https://mytarget.url.com"
            # optional site fields
            "form_login_url": "https://mytarget.url.com/login,
            "form_login_check_pattern": "",
            "form_login": [],
            "headers": [],
            "cookies": [],
            "whitelist": []
        },
        "scan_profile": "Normal",
        // optional scheduled_scan data
        "scheduledscan_datetime": "2022-12-30T12:34:56.224739",
        "scheduledscan_recurrence": "m"
    },
]

Request​

Body

required

    site

    object

    required

    Core settings of the target.
    Includes basic target information (like the name, description, and URL) and scanning information (like the authentication and navigation sequences).

    name string

    Possible values: <= 255 characters

    Name of the target or extra host.
    The maximum length is 255 characters.

    desc stringnullable

    Description of the target.

    url uri

    URL of the target.

    has_form_login boolean

    If true, the target authentication is done through a login form.
    Read more about how to set up target authentication (login form).
    Defaults to false.

    form_login_url uri

    URL of the login form of the target.

    form_login_check_pattern string

    Possible values: <= 255 characters

    Pattern to check a successful login.
    The maximum length is 255 characters.

    form_login

    object[]

    Field and value pairs to fill the login form.

  • Array [

    • name stringrequired
    value stringrequired

  • ]

    • logout_detection_enabled boolean

    If true, detects any undesired logouts that may occur during scans to log back in.
    Requires check_session_url and logout_detectors to be defined.
    Defaults to false.

    has_sequence_login boolean

    If true, the target authentication is done through a recorded login sequence.
    Read more about how to set up target authentication (login sequence).
    Defaults to false.

    has_basic_auth boolean

    If true, the target authentication is done through username and password credentials.
    Defaults to false.

    basic_auth

    object

    Username and password credentials for the basic auth.

    username stringrequired

    Possible values: <= 255 characters

    password stringrequired

    Possible values: <= 255 characters

    headers

    object[]

    Custom headers to send.

  • Array [

    • name stringrequired
    value stringrequired
    allow_testing boolean
    authentication boolean

  • ]

    • cookies

    object[]

    Custom cookies to send.

  • Array [

    • name stringrequired
    value stringrequired
    allow_testing boolean
    authentication boolean

  • ]

    • whitelist

    object

    Additional paths to crawl and scan. For example, "archive/search?query=probely". Only relative paths are allowed. The blacklist takes precedence over the whitelist.

    property name* any

    Additional paths to crawl and scan. For example, "archive/search?query=probely". Only relative paths are allowed. The blacklist takes precedence over the whitelist.

    blacklist

    object

    URLs to avoid scanning. For example, "https://example.com/pic-delete.php*" or "*.archive.example.com". URLs need to be absolute and wildcards (*) are allowed. The blacklist takes precedence over the whitelist.

    property name* any

    URLs to avoid scanning. For example, "https://example.com/pic-delete.php*" or "*.archive.example.com". URLs need to be absolute and wildcards (*) are allowed. The blacklist takes precedence over the whitelist.

    auth_enabled boolean

    If true, the target has authentication.
    Defaults to false.

    logout_condition string

    Possible values: [any, all]

    Type of combination of the logout conditions:

    • any - Is logged out if any condition is verified.
    • all - Is logged out only if all condition are verified.
    check_session_url string

    URL to check session.

    has_otp boolean

    If true, the target has two-factor authentication (2FA).
    Read more about how to set up target two-factor authentication (2FA).
    Defaults to false.

    otp_secret string

    The seed/secret obtained when the QR code is displayed to be scanned by the third-party authenticator (TPA) app installed on the phone (e.g., Google Authenticator, 1Password, Authy, Microsoft Authenticator, etc.).
    Read more about how to set up target two-factor authentication (2FA).

    otp_algorithm string

    Possible values: [SHA1, SHA256, SHA512]

    Default value: SHA1

    Secure hash algorithm (SHA) to generate the one-time password (OTP):
    (Defaults to SHA1)

    • SHA1 - Sha1
    • SHA256 - Sha256
    • SHA512 - Sha512
    otp_digits integer

    Possible values: >= -2147483648 and <= 2147483647, [6, 7, 8]

    Default value: 6

    Number of digits of the one-time password (OTP):
    (Defaults to 6)

    • 6 - Six
    • 7 - Seven
    • 8 - Eight
    otp_field string

    CSS selector of the HTML element in the page to enter the one-time password (OTP).
    For example, a text input field. Read more about how to obtain a CSS selector.
    Defaults to "".

    otp_submit string

    CSS selector of the HTML element in the page to submit the one-time password (OTP). For example, a button.
    Read more about how to obtain a CSS selector.
    Defaults to "".

    otp_login_sequence_totp_value string

    Possible values: >= 6 characters and <= 8 characters

    One-time password (OTP) obtained at the time when the login sequence was recorded, i.e., the time-based one-time password (TOTP).
    Defaults to "".

    otp_type string

    stack

    object[]

    Technologies identified in the target during scans.
    The scanning engine uses them to fine-tune vulnerability tests and improve the explanation of how to fix vulnerabilities.

  • Array [

    • name Framework Name (string)required

    Possible values: <= 255 characters

    Name of the technology.
    For example, "PHP, "SQLite", "Python", "Apache", or "Wordpress".
    The maximum lenght is 255 characters.

  • ]

    • api_scan_settings

    object

    Scanning settings if the target is an API.

    api_schema_type string

    Possible values: [openapi, postman]

    Type of schema that defines the API:

    • openapi - OpenAPI schema.
    • postman - Postman collection.
    api_schema_url stringnullable
    api_schema_file stringnullable

    custom_api_parameters

    object[]

  • Array [

    • name stringrequired
    value stringrequired

  • ]

    • media_type string

    Possible values: [application/json, application/x-www-form-urlencoded]

    Format of the payload:

    • application/json - The payload is in JSON format in the request body.
    • application/x-www-form-urlencoded - The payload is encoded in the request URL.
    api_login_url string

    Possible values: <= 2048 characters

    URL to make the authentication request to the API.
    The maximum length is 2048 characters.

    api_login_payload string

    Possible values: <= 4096 characters

    Payload to send in the authentication request.
    The maximum length is 4096 characters.

    api_login_enabled boolean
    api_login_token_field string

    Possible values: <= 256 characters

    Field containing the authentication token in the response to the authentication request.
    The maximum length is 256 characters.

    token_prefix string

    Possible values: <= 16 characters

    Prefix to add to the authentication token.
    For example, "Bearer" or "JWT".
    The maximum length is 16 characters.

    token_parameter_name string

    Possible values: <= 256 characters

    Parameter name to send the authentication token.
    For example, "Authorization".
    The maximum length is 256 characters.

    token_parameter_location string

    Possible values: [cookie, header]

    Where to send the parameter name with the authentication token and the prefix:

    • cookie - Cookie
    • header - Header
    scan_profile string

    Identifier of the scan profile.

    type string

    Type of target.
    Possible values are "single" for a web application and "api" for an API.
    Defaults to "single".

    unlimited boolean

    If true, the target has unlimited scans.
    If false, the target scans consume credits.
    Learn more about unlimited scans vs scans with credits.

    report_type string

    Possible values: [default, executive_summary, owasp, pci, pci4, iso27001, hipaa]

    Type of scan report produced for the target:
    (Defaults to default)

    • default - Standard
    • executive_summary - Executive Summary
    • owasp - OWASP Top 10
    • pci - PCI v3.2.1
    • pci4 - PCI v4.0.1
    • iso27001 - ISO 27001
    • hipaa - HIPAA
    report_fileformat string

    Possible values: [pdf, docx]

    Report format for the target:
    (Defaults to pdf)

    • pdf - PDF file format.
    • docx - DOCX file format.

    labels

    object[]

    Labels of the target.

  • Array [

    • name stringrequired

    Possible values: <= 255 characters

    Name of the label.
    The maximum length is 255 characters.

    color string

    Possible values: Value must match regular expression ^[a-zA-Z0-9#_-]*$

    Color of the label, in RGB hexadecimal format prefixed with "#".
    For example, "#00FF00" for green.

  • ]

    • scanning_agent

    object

    nullable

    Return serializer_class with all fields as read_only except key. The key is the field use to retrieve the object in to_internal_value.

    This is for the drf-spectacular documentation generation.

    id string
    include_deduplicated_endpoints booleannullable

    If true, scans include deduplicated endpoints.
    If false or null, scans exclude deduplicated endpoints.
    A deduplicated endpoint has the same simhash as another scanned endpoint.

    teams

    object[]

  • Array [

    • id string

    A unique Base58 value identifying this object.

  • ]

    • blackout_period

    object

    Time window during which scans are temporarily interrupted.

    begin timerequired

    Time of when the blackout period starts, in ISO 8601 UTC format.
    For example, "13:27".

    cease timerequired

    Time of when the blackout period ceases, in ISO 8601 UTC format.
    For example, "13:27".

    weekdays integer[]required
    enabled boolean

    If true, the blackout period is enabled.

    timezone string

    Possible values: <= 64 characters

    fail_fast boolean

    If true, scans fail on recoverable errors.
    If false, scans continue on recoverable errors.
    Defaults to true.

    incremental boolean

    If true, on-demand scans can be incremental to narrow the coverage to new and updated URLs.
    Learn more about partial scans.
    Defaults to false.

    reduced_scope boolean

    If true, on-demand scans can have reduced scope to narrow the coverage to defined URLs.
    Learn more about partial scans.
    Defaults to false.

    schedule_incremental boolean

    If true, scheduled scans can be incremental to narrow the coverage to new and updated URLs.
    Learn more about partial scans.
    Defaults to false.

    schedule_reduced_scope boolean

    If true, scheduled scans can have reduced scope to narrow the coverage to defined URLs.
    Learn more about partial scans.
    Defaults to false.

    crawl_sequences_only boolean

    If true, on-demand scans can only crawl navigation sequences to narrow the coverage.
    Learn more about partial scans.
    Defaults to false.

    schedule_crawl_sequences_only boolean

    If true, scheduled scans can only crawl navigation sequences to narrow the coverage.
    Learn more about partial scans.
    Defaults to false.

Responses​

Schema

    target_ids string[]
    scan_ids string[]
Loading...