Skip to content

Static Application Security Testing

Aptori leverages industry-leading tools for static application security testing, including OpenGrep, GoSec, Bandit. Aptori maintains the aptori/scanners container image, so you can easily incorporate an up-to-date SAST scanner into your CI/CD pipeline. Results from running aptori/scanners static application security testing on your source code repository are published to the Aptori Platform, alongside any security issues found by other Aptori tools.

Prerequisites

  • Asset ID of a Repository

    • To create a Repository asset, navigate to Projects in the Aptori Platform. At the top of the page, click "Add +" > "Add a Repository". Select the Project to which the Repository belongs and enter a name for the Repository. Following the remaining step below.
    • To get the asset ID of an existing Repository asset , navigate to Projects in the Aptori Platform. Find the row for the asset and click the "ID" button next to the asset name in the "Asset" column. The asset ID is displayed in the popup window, and it may be copied.

  • Platform Key

    • To create a Platform Key, navigate to Keys in the Aptori Platform.

Running on a local repository path

With container runtime CLI tools such as Docker or nerdctl, you can run aptori/scanners on a local copy of your source code repository. For example, from the root directory of the source code, use Docker CLI to run a SAST scan:

docker run --rm -v "${PWD}:/src" \
    aptori/scanners scanners sast opengrep \
        --key {{Your Platform Key}} \
        --asset-id {{Your Asset ID}} \
        --labels "repository={{Your repo URL}}, branch=main"

Alternately, the Platform Key and Asset ID may be specified in environment variables. This is particularly helpful when running in CI/CD.

export APTORI_ACCESS_KEY={{Your Platform Key}}
export APTORI_ASSET_ID={{Your Asset ID}}

docker run --rm -v "${PWD}:/src" \
    --env APTORI_ACCESS_KEY --env APTORI_ASSET_ID \
    aptori/scanners scanners sast opengrep \
        --labels "repository={{Your repo URL}}, branch=main"

Labels

Labels allow you to add metadata to a SAST run. There are two labels that have special meaning in the Aptori Platform:

  • repository: The URL of your source code repository will be used to create links from Issues back to the source code. The URL need not be accessible by the Platform, only by users that may follow a link from an Issue.
  • branch: The branch in your source code repository for which the SAST run was performed. Aptori Platform uses the branch name to reference the appropriate revision of a file in the source code repository, when adding links to an Issue.

Running in CI/CD

Performing a SAST run in a CI/CD pipeline is easy with the aptori/scanners container. We recommend you use CI/CD variables to store details like the Platform Key and Asset ID.

GitLab example

Below is an example GitLab CI/CD definition (.gitlab-ci.yml). In the example, a job named aptori-sast is defined to run on merge requests. The job requires the following CI/CD variables to be defined in the GitLab project's CI/CD settings (Settings > CI/CD > Variables).

  • APTORI_ACCESS_KEY: Platform Key for reporting results. See above for how to create a key.
  • APTORI_ASSET_ID: ID of the repository asset being testing. See above for how to get ID of a repository asset.

Use this example to create or modify your own .gitlab-ci.yml file. This is a simple example. In your existing pipeline, you may already have a pipeline stage in which you want the job to run.

stages:
  - aptori

# Run Aptori SAST on the source code.  This job only runs on merge
# request commits, e.g., in order to detect issues before merging
# into the default branch.
#
# The following variables must be defined in CI/CD settings.
#
# - APTORI_ACCESS_KEY
# - APTORI_ASSET_ID
#
aptori-sast:
  rules:
    - if: $CI_MERGE_REQUEST_IID
  stage: aptori
  image: aptori/scanners
  script:
    - scanners sast opengrep --labels "repository=${CI_PROJECT_URL}, branch=${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME}"

CircleCI example

In the following CircleCI example, a job named aptori-sast is defined to perform SAST on the source code of the repository. The job expects the following Environment Variables to be defined in the Project Settings.

  • APTORI_ACCESS_KEY
  • APTORI_ASSET_ID
version: 2.1
jobs:
  aptori-sast:
    # Scan codebase for security issues using Aptori Scanners.
    # Requires variables to be defined: APTORI_ACCESS_KEY, APTORI_ASSET_ID
    docker:
      - image: aptori/scanners
    steps:
      - checkout
      - run:
          name: Run Aptori SAST
          command: scanners sast opengrep --labels="repository=${CIRCLE_REPOSITORY_URL}, branch=${CIRCLE_BRANCH}, job=${CIRCLE_BUILD_URL}"
workflows:
  build-and-test:
    jobs:
      - aptori-sast

Command Reference

The SAST command has the following syntax:

scanners sast opengrep [OPTIONS]

Values for key and asset-id options are required, but they may be supplied by environment variables APTORI_ACCESS_KEY and APTORI_ASSET_ID, respectively. If both the CLI argument and environment variable are present, the CLI argument takes precedence.

Options

Option Description Environment variable
--help, -h Show help message and exit
--asset-id, -a Asset ID of a repository defined in Aptori Platform APTORI_ASSET_ID
--command, -c Pass custom command arguments to the opengrep CLI
--environment-id, -e Environment ID where SAST run is being performed APTORI_ENVIRONMENT_ID
--key, -k Aptori Platform key APTORI_ACCESS_KEY
--labels, -l Labels for the run, in format of "key1=value1, key2=value2"
--platform-url, -p Specify the Aptori Platform URL APTORI_PLATFORM_URL