BLACKSHIELD

Guida pubblica

Deploy the Pipeline Scanner

Embed Trivy, Syft, and TruffleHog into every commit with a single workflow file. Semgrep remains available when you provide local or customer-owned rules. Pubblico: DevOps engineers, platform engineers, and security engineers. Tempo medio di configurazione: 2 minutes.

Start herejourney

Use this if

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

Audience
DevOps engineers, platform engineers, and security engineers
Typical time
2 minutes

Start here

Step 3 of 6

Recommended
1
2
3
4
5
6

Prima di iniziare

  • 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.

Do this now

Passo 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.

What success looks like

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

Open API Keys · Sign-in required

Passo 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.

What success looks like

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

Scanner Licensing Defaults

Passo 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.

What success looks like

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

View Findings · Sign-in required

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.6 \
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.6 \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/gitlab-ci.sh)
Download source

Esegui

GitHub Actions — baseline scanners in parallel

yaml
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.6

GitLab CI — baseline scanners

yaml
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.6
  script: [python -m pipeline.entrypoint]
  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

bash
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.6

One-shot local scan (Trivy)

bash
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.6

What success looks like

  • 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).
Deploy the Pipeline Scanner | BlackShield Docs