从这里开始journey

适用场景

Embed Trivy, Syft, and TruffleHog into every commit with a single workflow file. Semgrep remains available when you provide local or customer-owned rules.

目标受众: DevOps engineers, platform engineers, and security engineers预计耗时: 2 minutes

从这里开始

Step 4 of 7

开始之前

Create an ingestion API key in Settings → API Keys with Ingestion scope only.
Confirm your CI runner can pull images from public.ecr.aws and reach your API URL.
For TruffleHog secret scanning: ensure fetch-depth: 0 is set in your checkout step so the local checkout includes full history.

立即执行

步骤 1

Create an ingestion API key

Generate a scoped key for the pipeline scanner and store it in your CI secret manager.

Open Settings → API Keys → New Key.
Set scope to Ingestion only.
Name it after the repository or pipeline (e.g. pipeline-my-repo).
Add BLACKSHIELD_API_KEY as a masked CI secret and BLACKSHIELD_API_URL as a CI variable.

达成目标状态

Add BLACKSHIELD_API_KEY as a masked CI secret and BLACKSHIELD_API_URL as a CI variable.

Open API Keys · 需要登录

步骤 2

Add the workflow file

Drop one file into your repository. The default matrix runs the safe baseline scanners in parallel.

Copy developer_guide/github/security-scan.yml or developer_guide/gitlab/gitlab-ci.yml from the Developer Guide.
The matrix runs trivy, trufflehog, and syft in parallel — no extra configuration.
Enable the optional Semgrep job only after adding a checked-in local rules file and setting `SEMGREP_CONFIG`.
TruffleHog automatically uses fetch-depth: 0 to scan all commit history.
The optional gate job blocks PR merges when critical findings are open.

达成目标状态

The optional gate job blocks PR merges when critical findings are open.

Scanner Licensing Defaults

步骤 3

Validate and expand

Confirm findings appear in the platform, then roll out to more repositories.

Trigger a pipeline run and check the platform Findings view.
Filter by scanner and repository to confirm metadata is correct.
Copy the workflow to additional repositories — each uses the same API key.
For GitLab: copy .gitlab-ci.yml snippet; for Bitbucket: copy bitbucket-pipelines.yml snippet.

达成目标状态

For GitLab: copy .gitlab-ci.yml snippet; for Bitbucket: copy bitbucket-pipelines.yml snippet.

View Findings · 需要登录

Demonstration only

This configuration is designed for ease of use. To deploy scanner clients at scale, please plan your deployment architecture accordingly or contact us for enterprise best practices.

Get the source bundle

Download the exact source files referenced on this page, or run the one-command installer to write them locally before following the deployment steps.

GitHub Actions workflow

Writes `.github/workflows/security-scan.yml` with Trivy, Syft, and TruffleHog defaults plus an optional local-rule Semgrep job.

.github/workflows/security-scan.yml

bash

BLACKSHIELD_PIPELINE_IMAGE=public.ecr.aws/blackshield-security/pipeline-scanner:1.0.14 \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/github-security-scan.sh)

Download source

GitLab CI pipeline

Writes `.gitlab-ci.yml` with Trivy, Syft, and TruffleHog defaults, schedule support, and optional local-rule Semgrep guidance.

.gitlab-ci.yml

bash

BLACKSHIELD_PIPELINE_IMAGE=public.ecr.aws/blackshield-security/pipeline-scanner:1.0.14 \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/gitlab-ci.sh)

Download source

Bitbucket Pipelines workflow

Writes `bitbucket-pipelines.yml`, configures repository variables through the Bitbucket API, and optionally commits a BlackShield branch.

bitbucket-pipelines.yml

bash

BLACKSHIELD_PIPELINE_IMAGE=public.ecr.aws/blackshield-security/pipeline-scanner:1.0.14 \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/bitbucket-pipelines.sh)

Download source

运行命令

GitHub Actions — baseline scanners in parallel

name: Security Scan
on:
  push:
    branches: [main, develop]
  pull_request:

jobs:
  pipeline-scan:
    name: "${{ matrix.tool }}"
    runs-on: ubuntu-latest
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        tool: [trivy, trufflehog, syft]
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: ${{ matrix.tool == 'trufflehog' && 0 || 1 }}
      - name: "Run ${{ matrix.tool }}"
        run: |
          docker run --rm \
            -e BLACKSHIELD_API_URL="${{ vars.BLACKSHIELD_API_URL }}" \
            -e BLACKSHIELD_API_KEY="${{ secrets.BLACKSHIELD_API_KEY }}" \
            -e SCAN_TOOL="${{ matrix.tool }}" \
            -e SCAN_TARGET="/workspace" \
            -e REPOSITORY_NAME="${{ github.repository }}" \
            -e SCAN_INTERVAL_SECONDS="0" \
            -v "${{ github.workspace }}:/workspace:ro" \
            public.ecr.aws/blackshield-security/pipeline-scanner:1.0.14

GitLab CI — baseline scanners

variables:
  BLACKSHIELD_API_URL: "https://api.blackshield.chaplau.com"
  # BLACKSHIELD_API_KEY: set in CI/CD → Variables (masked)

.scanner-base: &scanner-base
  stage: security
  image: public.ecr.aws/blackshield-security/pipeline-scanner:1.0.14
  entrypoint: [""]
  script: [/usr/local/bin/pipeline-scanner]
  variables:
    SCAN_TARGET: "$CI_PROJECT_DIR"
    REPOSITORY_NAME: "$CI_PROJECT_PATH"
    SCAN_INTERVAL_SECONDS: "0"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_PIPELINE_SOURCE == "schedule"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

scan:trivy:    { <<: *scanner-base, variables: { SCAN_TOOL: trivy } }
scan:syft:     { <<: *scanner-base, variables: { SCAN_TOOL: syft } }
scan:trufflehog:
  <<: *scanner-base
  before_script: [git fetch --unshallow || true]
  variables: { SCAN_TOOL: trufflehog }

Optional Semgrep SAST with local rules

docker run --rm \
  -e BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
  -e BLACKSHIELD_API_KEY=sp_xxxx \
  -e SCAN_TOOL=semgrep \
  -e SCAN_TARGET=/workspace \
  -e SEMGREP_CONFIG=/workspace/.semgrep/customer-rules.yml \
  -e SCAN_INTERVAL_SECONDS=0 \
  -v "$(pwd):/workspace:ro" \
  public.ecr.aws/blackshield-security/pipeline-scanner:1.0.14

One-shot local scan (Trivy)

docker run --rm \
  -e BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
  -e BLACKSHIELD_API_KEY=sp_xxxx \
  -e SCAN_TOOL=trivy \
  -e SCAN_TARGET=/workspace \
  -e SCAN_INTERVAL_SECONDS=0 \
  -v "$(pwd):/workspace:ro" \
  public.ecr.aws/blackshield-security/pipeline-scanner:1.0.14

达成目标状态

Pipeline run completes with exit code 0 for Trivy, Syft, and TruffleHog.
Findings appear in the platform Findings view with the correct repository name.
Resubmitting the same scan does not create duplicate findings (deduplication working).

下一步

Keep your rollout moving with the next recommended step.

导入首批发现

实用链接

Open API Keys View Findings Scanner Licensing Defaults Workload Identity All Deployment Guides

Deploy the Pipeline Scanner

适用场景

Step 4 of 7

开始之前

立即执行

Create an ingestion API key

Add the workflow file

Validate and expand

Get the source bundle

GitHub Actions workflow

GitLab CI pipeline

Bitbucket Pipelines workflow

运行命令

达成目标状态

下一步

实用链接

相关指南