@escape.tech/action

Escape CLI

Escape CLI is a command line interface for Escape.

It allows you to run Escape actions from the command line.

Installation

$ npm install -g @escape.tech/action

Usage

$ escape-action --help
Options:
      --version  Display the version number                            [boolean]
  -o, --output   Specify the JSON output file                           [string]
      --no-fail  Do not fail the CI if there are vulnerabilities.
                                                      [boolean] [default: false]
  -r             Show remediations in report.         [boolean] [default: false]
      --pdf      Download pdf report.                 [boolean] [default: false]
      --zip      Download exchange archive (zip file).[boolean] [default: false]
  -h, --help     Show help                                             [boolean]

Setup

This action requires an application ID and an API key to be provided. You can find both of these in the settings tab of your application on escape.

• ESCAPE_APPLICATION_ID: The application id to run the action on
• ESCAPE_API_KEY: The API key to use to authenticate with Escape
• TIMEOUT: The timeout for the action to run (default: 1200, 0 is non blocking action)
• FAIL_ON_SEVERITIES: a csv-delimited string that should contain either of these severities to define a failure of the cli (exit code 1)
  • HIGH
  • MEDIUM
  • LOW
  • INFO
• FAIL_ON_COMPLIANCE: a JSON string to define exact controls in an array (or all of them with *), per compliance framework supported
  • OWASP
  • PCI_DSS
  • GDPR
  • SOC2
  • PSD2
  • ISO27001
  • NIST
  • FEDRAMP

And all exact control values are documented at https://docs.escape.tech/documentation/dast/vulnerabilities/

{
  "OWASP": ["API8:2023", "API7:2023"],
  "PCI_DSS": ["*"],
  "GDPR": ["Article-32"],
  "NIST": ["*"],
  "FEDRAMP": ["AC-4"]
}

And you get feedback in error logs to review the exact failure reasons:

2024-02-07 08:28:32 [ error ] Exiting with status code 1 because alerts violated compliance configuration, detailed results: [{"testName":"Invalid input format detected","complianceFramework":"OWASP","complianceControlValue":"API8:2023","inViolation":true},{"testName":"Invalid input format detected","complianceFramework":"PCI_DSS","complianceControlValue":"6.5.1","inViolation":true},{"testName":"Invalid input format detected","complianceFramework":"GDPR","complianceControlValue":"Article-32","inViolation":true},{"testName":"Misconfigured Allow-Origin header","complianceFramework":"OWASP","complianceControlValue":"API7:2023","inViolation":true},{"testName":"Misconfigured Allow-Origin header","complianceFramework":"PCI_DSS","complianceControlValue":"6.5.10","inViolation":true},{"testName":"Misconfigured Allow-Origin header","complianceFramework":"GDPR","complianceControlValue":"Article-32","inViolation":true},{"testName":"Misconfigured Allow-Origin header","complianceFramework":"FEDRAMP","complianceControlValue":"AC-4","inViolation":true},{"testName":"Insecure Security Policy header","complianceFramework":"OWASP","complianceControlValue":"API7:2023","inViolation":true},{"testName":"Insecure Security Policy header","complianceFramework":"PCI_DSS","complianceControlValue":"6.5.10","inViolation":true},{"testName":"Insecure Security Policy header","complianceFramework":"GDPR","complianceControlValue":"Article-32","inViolation":true},{"testName":"Content-Type sniffing enabled","complianceFramework":"OWASP","complianceControlValue":"API7:2023","inViolation":true},{"testName":"Content-Type sniffing enabled","complianceFramework":"PCI_DSS","complianceControlValue":"6.5.10","inViolation":true},{"testName":"Content-Type sniffing enabled","complianceFramework":"GDPR","complianceControlValue":"Article-32","inViolation":true},{"testName":"Content-Type sniffing enabled","complianceFramework":"FEDRAMP","complianceControlValue":"AC-4","inViolation":true},{"testName":"Debug mode enabled","complianceFramework":"OWASP","complianceControlValue":"API7:2023","inViolation":true},{"testName":"Debug mode enabled","complianceFramework":"PCI_DSS","complianceControlValue":"6.5.5","inViolation":true},{"testName":"Debug mode enabled","complianceFramework":"GDPR","complianceControlValue":"Article-32","inViolation":true},{"testName":"Missing X-Frame-Options header","complianceFramework":"OWASP","complianceControlValue":"API7:2023","inViolation":true},{"testName":"Missing X-Frame-Options header","complianceFramework":"PCI_DSS","complianceControlValue":"6.5.1","inViolation":true},{"testName":"Missing X-Frame-Options header","complianceFramework":"GDPR","complianceControlValue":"Article-32","inViolation":true}]

For detailed instructions on how to set up your application, please refer to the Escape CI/CD documentation.

JSON Output

With the -o / --output cli options, you can get a JSON formatted file report of your scan, for example to store in a Jenkins build artifact.

{
  "id": "xxxx",
  "status": "SUCCESS",
  "duration": 55.618,
  "createdAt": "2024-02-01T16:17:09.631Z",
  "createdSince": 54,
  "completionRatio": 1,
  "readonlyAccessToken": "xxx",
  "securityTests": [
    {
      "failureName": "Invalid input format detected",
      "ignored": false,
      "alerts": [{ "ignored": false }],
      "severity": "HIGH"
    }
  ],
  "filteredSecurityTests": [
    {
      "failureName": "Invalid input format detected",
      "ignored": false,
      "alerts": [{ "ignored": false }],
      "severity": "HIGH"
    }
  ]
}

PDF report

The --pdf option allows you to download a PDF report of the scan results. The report includes information about the security tests that were run, the results of those tests, and any remediations that are recommended. The PDF report will be saved to the current directory.

Exchange Archive

The --zip option allows you to download an exchange archive (zip file) of the scan results. The archive includes the raw JSON data for the scan results, as well as any attachments that were uploaded during the scan. The exchange archive will be saved to the current directory.

Remediation in report

The --r option allows you to include remediations in the report. Remediations are recommended actions that can be taken to address any security vulnerabilities that are found during the scan. The report will be printed to the console, and will include the remediations for any security tests that failed.