AppCheck's Command Line Interface (CLI) tools allow users to use AppCheck's API within automated processes, enabling integration with CI/CD pipelines.

1. Create CI/CD Token
2. Download
3. Install
4. Configure

Create CI/CD Token

CI/CD tokens can be managed by admin users in the CI/CD Tokens page within the AppCheck Portal.

If you are an admin user and you do not see the CI/CD tokens page in the sidebar, use this form to request access.  If your organisation is not licensed for CI/CD integration your account manager will contact you.

Click "New CI/CD Token" in the top right to create a new token, or the pencil icon next to an existing token to edit it.

You will need to provide the public IP address from which your API requests will come; often this will be the address of your outbound gateway or proxy server.  Private (internal) addresses usually begin with 192, 172 or 10 - if this is the IP address you see then you may need to speak to your network administrator to get your public address.  You may find you have multiple public addresses, which may be alternated between - in this case, you will need to add them all to your account's allow list.

All CI/CD Tokens are associated with an AppCheck user.  You may wish to create a dedicated user for your integration, to make it clear in logs which service/user initiated actions.  The level of user you need to create will depend on the actions you wish to perform as part of your integration.  If you wish to create scans, then you will need to use an admin user.  If you wish only to run scans, or view results, then a standard user will be sufficient if it is added to appropriate user groups.

Download

To download the AppCheck CLI tool log in to the AppCheck Portal and select Downloads in the side bar.  The tool is provided as an installer for various systems as well as in binary form.

Install

Install the tool on your CI/CD server.  Ensure it has outbound access to AppCheck's servers.

Configure

Authentication

AppCheck CLI requires a client ID to interact with the AppCheck NG API. The client ID is your API key. You can provide it in three ways (listed in order of precedence):

1. Command-line flags (highest priority)
2. Environment variables
3. Configuration file (lowest priority)

Using Environment Variables

Set the following environment variable:

export CLIENT_ID="your_api_key_here"

To use an alternative API base URL:

export BASE_URL="https://127.0.0.1:8080/api/v1"

Using Configuration File

Create an appcheck-ci.yml file in your project root with your configuration:

# AppCheck CI/CD Configuration File
appcheck-ci:
  # Optional: Configuration schema version
  version: "1.0"
  
  # API authentication (required)
  # client_id is your AppCheck API key
  client_id: "your-api-key-here"

  # Optional: Override default API base URL
  # base_url: "https://api.appcheck-ng.com/api/v1/"

  # Polling
  poll_interval: 10

  # Export Options
  export_xlsx: "report.xlsx"
  export_html: "report.html"
  export_sarif: "results.sarif"

Environment variables are currently supported for CLIENT_ID and BASE_URL only.

The tool will automatically look for appcheck-ci.yml in the current directory. To use a different location:

./appcheck-cli -f /path/to/config.yml --scan-id your_scan_id --action run

See appcheck-ci.yml.example for a complete configuration file template with all available options.

Using Command-Line Flags

You can override configuration file values, and you can provide supported environment-backed settings directly on the command line:

./appcheck-cli --client-id "your_api_key" --scan-id your_scan_id --action run

Commands

Run a Scan

To start a new scan, wait for it to complete, and then display vulnerabilities:

./appcheck-cli --action run --scan-id your_scan_id --display-vulns

Start a Scan

To start a new scan without waiting for it to complete:

./appcheck-cli --action start --scan-id your_scan_id

Stop a Scan

To stop an ongoing scan:

./appcheck-cli --scan-id your_scan_id --action stop

Pause a Scan

To pause a running scan:

./appcheck-cli --scan-id your_scan_id --action pause

Resume a Scan

To resume a paused scan:

./appcheck-cli --scan-id your_scan_id --action resume

Fetch the Last Results of a Scan

Retrieve the most recent results of a scan:

./appcheck-cli --scan-id your_scan_id --action results --display-vulns

Show the Current Status of a Scan

Check the status of an ongoing scan, useful for non-blocking scans or managing multiple scans:

./appcheck-cli --scan-id your_scan_id --action status

Show Scan Status Without Banner

Display the status of a scan without the banner, useful for scripting:

./appcheck-cli --scan-id your_scan_id --action status --no-banner

Wait for a Scan to complete and Display Vulnerabilities

To wait for a running scan to complete, then display vulnerabilities:

./appcheck-cli --action watch --scan-id your_scan_id --display-vulns

Show Scan Details

View detailed information about the current scan, including targets, progress, name, and vulnerability counts:

./appcheck-cli --scan-id your_scan_id --action details

Export Vulnerability Reports

Export scan results to Excel, HTML, or SARIF format for offline analysis and reporting.

Export to Excel (XLSX)

Generate a comprehensive Excel spreadsheet with all vulnerability details:

./appcheck-cli --scan-id your_scan_id --action results --export-xlsx vulnerabilities.xlsx

You can also pipe the output to stdout for further processing:

./appcheck-cli --scan-id your_scan_id --action results --export-xlsx - > vulnerabilities.xlsx

The Excel report includes the following columns:

• Title
• Impact
• Host
• CVSS Score
• CVSS Vector
• IPv4
• First Detected
• Last Detected
• ID
• URL
• Target
• Status
• Link to Vulnerability (clickable hyperlink)
• Notes

Impact levels are colour-coded for easy identification:

• Critical: Dark red background
• High: Red background
• Medium: Yellow background
• Low: Green background
• Info: Blue background

Export to HTML Report

Generate a professional HTML report with a table of contents and detailed vulnerability information:

./appcheck-cli --scan-id your_scan_id --action results --export-html report.html

You can also pipe the output to stdout:

./appcheck-cli --scan-id your_scan_id --action results --export-html - > report.html

Or combine it with other tools:

./appcheck-cli --scan-id your_scan_id --action results --export-html - | tee report.html | wc -l

The HTML report features:

• Searchable table of contents with quick navigation
• Summary statistics dashboard
• Colour-coded impact badges
• Full vulnerability details including synopsis and remediation steps
• CVSS scores and vectors
• Timeline of detection (first and last detected dates)
• Clickable links to view vulnerabilities in the AppCheck scanner
• Responsive design that works on desktop and mobile devices

Export to SARIF Format

Generate a SARIF (Static Analysis Results Interchange Format) report for integration with GitHub Code Scanning, Azure DevOps, and other tools:

./appcheck-cli --scan-id your_scan_id --action results --export-sarif results.sarif

You can also pipe the output to stdout:

./appcheck-cli --scan-id your_scan_id --action results --export-sarif - > results.sarif

The SARIF export includes:

• SARIF v2.1.0 compliant format
• Vulnerability details mapped to SARIF rules
• Impact levels mapped to SARIF severity (critical/high→error, medium→warning, low/info→note)
• Location information (host, target, URL)
• CVSS scores and vectors as properties
• Detection timeline metadata

Note: Whilst SARIF is designed for static analysis tools, this export provides best-effort mapping of dynamic vulnerability scan results to the SARIF format for integration with security dashboards and CI/CD pipelines.

Export Multiple Formats Simultaneously

You can generate multiple report formats in a single command:

./appcheck-cli --scan-id your_scan_id --action run --export-xlsx report.xlsx --export-html report.html --export-sarif results.sarif --display-vulns

This is particularly useful for CI/CD pipelines where you want to:

• Archive Excel files for record-keeping
• Publish HTML reports for easy team access
• Upload SARIF results to GitHub Code Scanning or Azure DevOps

Note: When exporting reports, the CLI automatically fetches full vulnerability details including synopsis, CVSS information, and all metadata. This may take slightly longer than standard result fetching.

Configuration File

AppCheck CLI supports YAML configuration files for simplified deployment and consistent settings across environments. This is particularly useful for CI/CD pipelines where you want to maintain configuration in version control.

Configuration File Location

By default, the tool looks for appcheck-ci.yml in the current working directory. You can specify an alternative location using the -f flag:

./appcheck-cli -f /path/to/my-config.yml --scan-id your_scan_id --action run

Configuration File Format

Create an appcheck-ci.yml file with your desired settings:

appcheck-ci:
  # Optional: Configuration schema version
  version: "1.0"
  
  # API Authentication (required)
  # client_id is your AppCheck API key
  client_id: "your-api-key-here"

  # Optional: Override API base URL
  # base_url: "https://api.appcheck-ng.com/api/v1/"

  poll_interval: 10       # Check status every 10 seconds

  # Export Options
  export_xlsx: "report.xlsx"
  export_html: "report.html"
  export_sarif: "results.sarif"

  # Or pipe to stdout:
  # export_xlsx: "-"
  # export_html: "-"
  # export_sarif: "-"

Configuration Precedence

Settings are applied in the following order (later sources override earlier ones):

1. Configuration file (lowest priority)
2. Environment variables for settings that support them
3. Command-line flags (highest priority)

This allows you to:

• Set defaults in a config file
• Override supported settings with environment variables in CI/CD
• Override specific values with command-line flags for testing

Example: Configuration File with CLI Overrides

Given this appcheck-ci.yml:

appcheck-ci:
  version: "1.0"
  client_id: "your-api-key"
  export_html: "report.html"

Running this command:

./appcheck-cli --scan-id abc123 --action run --export-html "-"

Results in:

• client_id from config file: "your-api-key"
• export_html from CLI flag: "-" (stdout, overriding config file)

CI/CD Integration with Configuration Files

Configuration files work seamlessly with environment variable substitution in CI/CD platforms. Store the config file in your repository and use CI/CD secrets for sensitive values:

# appcheck-ci.yml in repository
appcheck-ci:
  version: "1.0"
  client_id: "${CLIENT_ID}"      # Will be replaced by CI/CD
  export_sarif: "results.sarif"

Note: The tool reads the YAML file directly. Environment variable substitution must be performed by your CI/CD platform (e.g., using envsubst or native CI/CD features) before the tool runs.

Retry and Timeout Configuration

The CLI includes built-in retry logic for handling transient network failures and server errors (HTTP 5xx status codes). By default, failed requests are automatically retried up to 25 times with a 5-second wait between attempts, and each request has a 600-second (10-minute) timeout.

Customise Retry and Timeout Settings

To adjust the retry count and timeout values:

./appcheck-cli --scan-id your_scan_id --action run --default-retries 10 --default-timeout 300

This example sets:

• Maximum of 10 retry attempts
• 300-second (5-minute) timeout per request

Disable Retries

To disable automatic retries entirely:

./appcheck-cli --scan-id your_scan_id --action run --default-retries 0

Unlimited Retries

For scenarios where you want the CLI to retry indefinitely until successful (use with caution):

./appcheck-cli --scan-id your_scan_id --action run --default-retries -1

Warning: Using -1 for unlimited retries may cause the application to hang indefinitely if the service is permanently unavailable. Only use this in environments where you have external monitoring or timeout mechanisms.

Common Scenarios

For unstable networks or slow connections:

./appcheck-cli --scan-id your_scan_id --action run --default-retries 50 --default-timeout 900

For fast, reliable networks:

./appcheck-cli --scan-id your_scan_id --action run --default-retries 5 --default-timeout 120

Note: The retry mechanism automatically handles:

• Network timeouts
• HTTP 5xx server errors
• Connection failures

Between retry attempts, the CLI waits 5 seconds before trying again.

Flags

General

• --version: Show version information and exit.

Configuration

• -f: Path to YAML configuration file (e.g., appcheck-ci.yml). If not specified, looks for appcheck-ci.yml in the current directory.

API Authentication

• --client-id: AppCheck client ID, which is your API key (or set CLIENT_ID environment variable).
• --base-url: Override API base URL (or set BASE_URL environment variable).

Scan Control

• --scan-id: The ID of the scan (required for all actions except --version).
• --action: The action to perform: run, start, stop, pause, resume, watch, wait, status, results, or details.
• --poll-interval: Polling interval in seconds when waiting for scan completion (default: 10).

Display Options

• --display-vulns: Display vulnerability titles and impacts.
• --no-banner: Do not display the banner on launch, useful for scripting.
• -v: Enable verbose logging output for debugging and detailed operation tracking.

Failure Thresholds

These checks are evaluated when the CLI produces a final scan report, such as with run, watch, or wait.

• --fail-critical: Exit with code 1 for CI/CD if the number of critical vulnerabilities exceeds the configured threshold.
• --fail-high: Exit with code 1 for CI/CD if the combined number of critical and high vulnerabilities exceeds the configured threshold.
• --fail-medium: Exit with code 1 for CI/CD if the combined number of critical, high, and medium vulnerabilities exceeds the configured threshold.
• --fail-low: Exit with code 1 for CI/CD if the combined number of critical, high, medium, and low vulnerabilities exceeds the configured threshold.
• --fail-any: Exit with code 1 for CI/CD if the total number of vulnerabilities exceeds the configured threshold.
• --fail-critical-count: The maximum count allowed for critical vulnerabilities before the build fails (defaults to 0).
• --fail-high-count: The maximum combined count allowed for critical and high vulnerabilities before the build fails (defaults to 0).
• --fail-medium-count: The maximum combined count allowed for critical, high, and medium vulnerabilities before the build fails (defaults to 0).
• --fail-low-count: The maximum combined count allowed for critical, high, medium, and low vulnerabilities before the build fails (defaults to 0).
• --fail-any-count: The maximum total count allowed across all severities before the build fails (defaults to 0).

HTTP Client Configuration

• --default-retries: Number of automatic retries for failed HTTP requests (defaults to 25). Set to 0 to disable retries, or -1 for unlimited retries.
• --default-timeout: Timeout in seconds for each HTTP request (defaults to 600 seconds / 10 minutes).

Export Options

• --export-xlsx: Export vulnerabilities to an Excel file (e.g., report.xlsx) or use - for stdout. Includes comprehensive vulnerability data with colour-coded impact levels.
• --export-html: Export vulnerabilities to an HTML report (e.g., report.html) or use - for stdout. Generates a professional, searchable report with table of contents.
• --export-sarif: Export vulnerabilities to SARIF format (e.g., results.sarif) or use - for stdout. SARIF v2.1.0 compliant format for integration with GitHub Code Scanning, Azure DevOps, and other security tools.

Example GitLab CI/CD Pipeline

GitLab .gitlab-ci.yml configuration for integrating AppCheck CLI into your GitLab CI/CD pipeline:

stages:
  - scan

variables:
  CLIENT_ID: "your_api_key_here"

scan_job:
  stage: scan
  script:
    - echo "Starting AppCheck scan"
    - ./appcheck-cli --action run --scan-id $SCAN_ID --display-vulns --export-xlsx report.xlsx --export-html report.html
  artifacts:
    paths:
      - report.xlsx
      - report.html
    expire_in: 30 days
  only:
    - branches

In the above example:

• Replace your_api_key_here with your AppCheck API key.
• Set the SCAN_ID variable to the ID of the scan you wish to run.
• The scan will generate both Excel and HTML reports as pipeline artifacts.

The above will start a scan for the given SCAN_ID and will block until complete or aborted. Upon completion, any resulting vulnerabilities will be displayed, and reports will be archived as build artifacts.

Example GitHub Actions Workflow

GitHub Actions workflow configuration for integrating AppCheck CLI into your GitHub Actions pipeline:

name: AppCheck Scan

on:
  push:
    branches:
      - main

jobs:
  scan_job:
    runs-on: ubuntu-latest
    env:
      CLIENT_ID: ${{ secrets.CLIENT_ID }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Run AppCheck Scan
        env:
          SCAN_ID: ${{ secrets.SCAN_ID }}
        run: ./appcheck-cli --action run --scan-id $SCAN_ID --display-vulns --export-xlsx report.xlsx --export-html report.html --export-sarif results.sarif

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

      - name: Upload Reports
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: vulnerability-reports
          path: |
            report.xlsx
            report.html
            results.sarif

In the above example:

• Store your AppCheck API key in CLIENT_ID and your scan ID in SCAN_ID in your GitHub repository secrets.
• Reports are uploaded as artifacts and available even if the scan fails.

The above will start a scan for the given SCAN_ID and will block until complete or aborted. Upon completion, any resulting vulnerabilities will be displayed, and reports will be available as workflow artifacts.

Example Azure DevOps Pipeline

Azure DevOps pipeline configuration for integrating AppCheck CLI into your Azure DevOps pipeline:

trigger:
  branches:
    include:
      - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  CLIENT_ID: $(CLIENT_ID)
  SCAN_ID: $(SCAN_ID)

steps:
  - script: |
      ./appcheck-cli --action run --scan-id $(SCAN_ID) --display-vulns --export-xlsx report.xlsx --export-html report.html
    displayName: 'Run AppCheck Scan'
    env:
      CLIENT_ID: $(CLIENT_ID)

  - task: PublishBuildArtifacts@1
    condition: always()
    inputs:
      pathToPublish: '$(System.DefaultWorkingDirectory)'
      artifactName: 'vulnerability-reports'
      includeRootFolder: false
    displayName: 'Publish Vulnerability Reports'

In the above example:

• Set CLIENT_ID to your AppCheck API key and SCAN_ID to your scan ID in your Azure DevOps project.
• Reports are published as build artifacts.

The above will start a scan for the given SCAN_ID and will block until complete or aborted. Upon completion, any resulting vulnerabilities will be displayed, and reports will be available as build artifacts.

Example Jenkins Pipeline

Jenkins pipeline configuration for integrating AppCheck CLI into your Jenkins pipeline:

pipeline {
    agent any
    environment {
        CLIENT_ID = credentials('appcheck-client-id')
        SCAN_ID = credentials('scan-id')
    }
    stages {
        stage('Run Scan') {
            steps {
                sh './appcheck-cli --action run --scan-id $SCAN_ID --display-vulns --export-xlsx report.xlsx --export-html report.html'
            }
        }
        stage('Archive Reports') {
            steps {
                archiveArtifacts artifacts: 'report.xlsx,report.html', allowEmptyArchive: false
            }
        }
    }
}

In the above example:

• Configure appcheck-client-id to hold your AppCheck API key, and scan-id to hold your scan ID.
• Reports are archived as build artifacts.

The above will start a scan for the given SCAN_ID and will block until complete or aborted. Upon completion, any resulting vulnerabilities will be displayed, and reports will be available as archived artifacts.

Example Jira Automation Rule

Jira Automation rule for integrating AppCheck CLI into your Jira automation:

1. Create a new Automation Rule:

   • Navigate to Jira settings > System > Automation rules.
   • Click "Create rule" and choose "Custom rule."

2. Configure the trigger:

   • Add a trigger for when an issue is created or transitioned to a specific status (e.g., "Ready for Scan").

3. Add a Webhook action:

   • Add a "Send web request" action.
   • Configure the webhook to trigger a build in your CI/CD system (GitHub Actions, Azure DevOps, Jenkins) which runs the AppCheck CLI scan.

For example, a webhook to trigger a GitHub Actions workflow might look like this:

{
  "ref": "main",
  "inputs": {
    "scan_id": "{{issue.fields.customfield_10000}}"
  }
}

• Replace {{issue.fields.customfield_10000}} with the custom field ID containing the scan ID in your Jira issue.

This setup assumes you have a way to trigger your CI/CD pipeline from a Jira webhook, and that your pipeline can start the AppCheck CLI scan using the provided scan ID.