Skip to content

hound672/BlackBox-CI-CD-script

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

15 Commits
blackbox_ci
blackbox_ci
 
 
docs
docs
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
main.py
main.py
 
 
poetry.lock
poetry.lock
 
 
pyproject.toml
pyproject.toml
 
 
requirements-dev.txt
requirements-dev.txt
 
 
requirements.txt
requirements.txt
 
 
setup.cfg
setup.cfg
 
 
tox.ini
tox.ini
 
 

Repository files navigation

blackbox-scan

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.

Requirements

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

Usage

Synopsis

  main.py [OPTIONS]

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.

Authorization data file

The file with authentication data contains KEY=VALUE pairs in its lines. Keys are:

  • TYPE - Authentication type, one of httpBasic 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 URL
  • SUCCESS_STRING - String for verifying authentication success
  • FORM_X_PATH - Xpath of a form in an HTML document
  • USERNAME_FIELD - Username field ID
  • PASSWORD_FIELD - Password field ID
  • REGEXP_OF_SUCCESS - Regexp for verifying authentication success
  • SUBMIT_VALUE - Submit button ID
  • COOKIES - Cookie strings separated by the ; character
  • SUCCESS_URL - Address of successful sign-in page
  • PLACE - Defines the api key transfer place: COOKIE, HEADER or QUERY
  • NAME - Query parameter name for QUERY or header name for COOKIE, HEADER
  • VALUE - Value of the api key
  • TOKEN - Value of the Bearer token

httpBasic

TYPE=httpBasic
USERNAME=username
PASSWORD=password

htmlAutoForm

TYPE=htmlAutoForm
USERNAME=username
PASSWORD=password
FORM_URL=http://staging.example.com/login/
SUCCESS_STRING=My profile

htmlFormBased

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

rawCookie

TYPE=rawCookie
COOKIES=PHPSESSID=bnc3li5jhmebd50suf9a99u0u3;SOMECOOKIE=1a2b3c4;
SUCCESS_URL=http://staging.example.com/after_login/
REGEXP_OF_SUCCESS=Logout

apiKey

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

bearer

SUCCESS_STRING is optional

TYPE=bearer
TOKEN=some-token-value
SUCCESS_URL=http://api.example.test:8000/auth/check
SUCCESS_STRING=Access granted

Environment

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/ key PASSWORD
  • AUTH_TOKEN/ key TOKEN
  • AUTH_API_KEY_VALUE/ key VALUE

Example

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

Results

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

Bugs and Issues

To report a problem related to the tool, please create a new issue.

Terms

For BlackBox terms of use, see BlackBox License.

License

For the tool licensing terms, see LICENSE file.

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license
Activity

Stars

5 stars

Watchers

2 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages