This tool is a command-line client for the BlackBox API, that can help to integrate Dynamic Application Security Testing (DAST) into a CI/CD pipeline.
Python version 3.8.19 or above is required to run the tool. The use of virtualenv or poetry is recommended.
To install required Python packages, run:
pip install -r requirements.txt
Or:
poetry install
main.py [OPTIONS]
Usage: main.py [OPTIONS]
Options:
--blackbox-url TEXT
--blackbox-api-token TEXT [required]
--target-url TEXT Set url of scan target. Do not use with
--target-file, --target-uuid.
--target-file FILENAME Set filename with target urls. Do not use
with --target-url, --target-uuid.
--target-uuid TEXT Set uuid of scan target. Do not use with
--target-url, --target-file.
--group-uuid TEXT Set group UUID for site
--ignore-ssl Skip verification of BlackBox API host
certificate.
--auto-create Automatically create a site if a site with
the target URL in the specified group was
not found.
--previous [wait|stop|fail] What to do if the target is currently being
scanned.
--no-wait Do not wait until the started scan is
finished.
--shared-link Create shared link for scan.
--scan-profile TEXT Set scan profile UUID for new scan
--auth-profile TEXT Set authentication profile UUID for site.
Cannot be used with --auth-data option. For
scanning without authentication specify
`RESET` in the option
--api-schema TEXT Set API-schema UUID for site. For scanning
without API-schema specify `RESET` in the
option
--fail-under-score FLOAT RANGE Fail with exit code 3 if report scoring is
less than given score (set "1" or do not set
to never fail). [1<=x<=10]
--report-dir DIRECTORY Set directory path for storing the generated
report file. If the option is used, the
report will be saved in the specified
directory. Cannot be used with --no-wait
option. To generate a report the scan must
be finished or stopped.
--report-template [html|nist|oud4|owasp|owasp_mobile|pcidss|sarif|sans]
Template shortname of the report to be
generated. Specifies file format for report
in --report-dir.
--report-locale [ru|en] Localization of the report file to be
generated. Specifies file localization for
report in --report-dir.
--results-only Only get results of specified site. Last
scan results by default. Use --scan-id
option to get results of specific scan.
--scan-id INTEGER RANGE Set the scan ID to get the results. Can be
used without --results-only option. [x>=1]
--auth-data FILENAME Set path to file with authentication data.
If this option is used, a new authentication
profile with the data provided will be
created and used for new scan. Cannot be
used with --auth-profile option. It is
highly recommended to use environment
variables to store passwords, tokens and api
keys: AUTH_PASSWORD, AUTH_TOKEN,
AUTH_API_KEY_VALUE
--help Show this message and exit.
The file with authentication data contains KEY=VALUE
pairs in its lines. Keys are:
TYPE
- Authentication type, one ofhttpBasic
htmlAutoForm
,htmlFormBased
,rawCookie
,apiKey
,bearer
.USERNAME
- Username which must be entered in the appropriate form field (its value)PASSWORD
- Password which must be entered in the appropriate form field (its value)FORM_URL
- Authorization page URLSUCCESS_STRING
- String for verifying authentication successFORM_X_PATH
- Xpath of a form in an HTML documentUSERNAME_FIELD
- Username field IDPASSWORD_FIELD
- Password field IDREGEXP_OF_SUCCESS
- Regexp for verifying authentication successSUBMIT_VALUE
- Submit button IDCOOKIES
- Cookie strings separated by the;
characterSUCCESS_URL
- Address of successful sign-in pagePLACE
- Defines the api key transfer place:COOKIE
,HEADER
orQUERY
NAME
- Query parameter name forQUERY
or header name forCOOKIE
,HEADER
VALUE
- Value of the api keyTOKEN
- Value of the Bearer token
TYPE=httpBasic
USERNAME=username
PASSWORD=password
TYPE=htmlAutoForm
USERNAME=username
PASSWORD=password
FORM_URL=http://staging.example.com/login/
SUCCESS_STRING=My profile
SUBMIT_VALUE
is optional
TYPE=htmlFormBased
FORM_URL=http://staging.example.com/login/
FORM_X_PATH=.//form
USERNAME_FIELD=login
USERNAME=username
PASSWORD_FIELD=pass
PASSWORD=password
REGEXP_OF_SUCCESS=Welcome to my site!
SUBMIT_VALUE=Log in
TYPE=rawCookie
COOKIES=PHPSESSID=bnc3li5jhmebd50suf9a99u0u3;SOMECOOKIE=1a2b3c4;
SUCCESS_URL=http://staging.example.com/after_login/
REGEXP_OF_SUCCESS=Logout
SUCCESS_STRING
is optional
TYPE=apiKey
PLACE=HEADER
NAME=X-Some-Header
VALUE=some-token-value
SUCCESS_URL=http://api.example.test:8000/auth/check
SUCCESS_STRING=Access granted
SUCCESS_STRING
is optional
TYPE=bearer
TOKEN=some-token-value
SUCCESS_URL=http://api.example.test:8000/auth/check
SUCCESS_STRING=Access granted
The following environment variables may be used instead of corresponding options:
BLACKBOX_URL
/--blackbox-url
BLACKBOX_API_TOKEN
/--blackbox-api-token
TARGET_URL
/--target-url
TARGET_UUID
/--target-uuid
TARGET_FILE
/--target-file
IGNORE_SSL
/--ignore-ssl
SCAN_PROFILE
/--scan-profile
GROUP_UUID
/--group-uuid
AUTH_PROFILE
/--auth-profile
API_SCHEMA
/--api-schema
It is recommended that you use these environment variables instead of the corresponding keys in the file with authentication data:
AUTH_PASSWORD
/ keyPASSWORD
AUTH_TOKEN
/ keyTOKEN
AUTH_API_KEY_VALUE
/ keyVALUE
export BLACKBOX_URL=https://bbs.ptsecurity.com/
export BLACKBOX_API_TOKEN=D4OPXw7mXCWjHER0lE48PCr4UkcfD86AwOwnio9I1w3HsOSS3Hxo9xi82hoWOB5deVYMk3kedgh0f9yq
export TARGET_URL=http://staging.example.com/
export GROUP_UUID=ee2e5f90-c9ee-454e-a4db-123463d29851
python main.py --auto-create --previous=stop --report_dir=/path/to/report/dir
When a scan finishes without an error, the tool returns exit code 0
and prints JSON-formatted report to stdout
. A report may be passed for processing to a tool such as jq.
Example output for --target-url
option (reformatted for readability):
{
"target_url": "http://staging.example.com/",
"target_uuid": "ccb7de77-ff51-464d-bf25-7ebcfe0403d6",
"url": "https://bbs.ptsecurity.com/sites/ccb7de77-ff51-464d-bf25-7ebcfe0403d6/scans/1",
"scan_status": "FINISHED",
"score": 1,
"sharedLink": "https://bbs.ptsecurity.com/shared/dee4Lyx",
"report_path": "/path/to/report/dir/20230825_182339_staging_example_com.ru.html",
"vulns": {
"issue_groups": [
{
"severity": "low",
"category": "sensitive_data",
"group_title": "server_software_version_disclosure",
"vulns": [
{
"url": "http://staging.example.com/"
},
{
"url": "http://staging.example.com/upload.php"
}
]
},
{
"severity": "high",
"category": "insecure_design",
"group_title": "fileupload",
"vulns": [
{
"url": "http://staging.example.com/upload.php"
}
]
},
{
"severity": "medium",
"category": "cryptography",
"group_title": "no_https_scheme",
"vulns": [
{
"url": "https://staging.example.com/"
}
]
}
],
"error_page_groups": [
{
"group_title": "404",
"category": "tech_info",
"vulns": [
{
"url": "http://staging.example.com/cgi-bin/"
}
]
},
{
"group_title": "501",
"category": "tech_info",
"vulns": [
{
"url": "http://staging.example.com/"
}
]
}
],
"cve_groups": [
{
"category": "cve",
"group_title": "Apache 2.4.43",
"vulns": [
{
"cve_id": "CVE-2021-26691",
"vector": "(CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H)"
},
{
"cve_id": "CVE-2020-9490",
"vector": "(CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H)"
}
]
}
]
},
"errors": null
}
Example output for --target-file
option (with --no-wait
option provided and without shared link generation):
[
{
"target_url": "http://first.example.com/",
"target_uuid": "ccb7de77-ff51-464d-bf25-7ebcfe0403d6",
"url": "https://bbs.ptsecurity.com/sites/ccb7de77-ff51-464d-bf25-7ebcfe0403d6/scans/1",
"scan_status": "IN_PROGRESS",
"score": null,
"sharedLink": null,
"report_path": null,
"vulns": null,
"errors": null
},
{
"target_url": "http://second.example.com/",
"target_uuid": "cce4cf46-1edf-443c-ae57-5b2abc8703bd",
"url": "https://bbs.ptsecurity.com/sites/cce4cf46-1edf-443c-ae57-5b2abc8703bd/scans/1",
"scan_status": "IN_PROGRESS",
"score": null,
"sharedLink": null,
"report_path": null,
"vulns": null,
"errors": null
},
{
"target_url": "http://third.example.com/",
"target_uuid": "cbb3971e-3a22-40b9-8d43-aceca9bc4b19",
"url": "https://bbs.ptsecurity.com/sites/cbb3971e-3a22-40b9-8d43-aceca9bc4b19/scans/1",
"scan_status": "IN_PROGRESS",
"score": null,
"sharedLink": null,
"report_path": null,
"vulns": null,
"errors": null
}
]
In case an error occurs, the tool returns non-zero exit code and prints error log messages to stderr
:
2021-12-03 13:24:52,517 ERROR [root] BlackBox error: the scan did not succeed, see UI for the error reason: http://bbs.ptsecurity.com/sites/ccb7de77-ff51-464d-bf25-7ebcfe0403d6/scans/1
To report a problem related to the tool, please create a new issue.
For BlackBox terms of use, see BlackBox License.
For the tool licensing terms, see LICENSE file.