BLACKSHIELD

دليل عام

Deploy the Pipeline Scanner

Embed Trivy, Semgrep, TruffleHog, and Syft into every commit with a single workflow file. Works with GitHub Actions, GitLab CI, and Bitbucket Pipelines. الجمهور: DevOps engineers, platform engineers, and security engineers. وقت الإعداد المعتاد: 2 minutes.

Start herejourney

Use this if

Embed Trivy, Semgrep, TruffleHog, and Syft into every commit with a single workflow file. Works with GitHub Actions, GitLab CI, and Bitbucket Pipelines.

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

قبل البدء

  • 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

الخطوة 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

الخطوة 2

Add the workflow file

Drop one file into your repository. The matrix strategy runs all four 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, semgrep, trufflehog, and syft in parallel — no extra configuration.
  • 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.

All Deployment Guides

الخطوة 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

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` into the current repository so the pipeline scanner can run immediately.

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

GitLab CI pipeline

Writes `.gitlab-ci.yml` into the current repository with the four scanner jobs, schedule support, and the current platform API URL prefilled.

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

نفّذ هذا

GitHub Actions — all four 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, semgrep, 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.0

GitLab CI — all four 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.0
  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:semgrep:  { <<: *scanner-base, variables: { SCAN_TOOL: semgrep } }
scan:syft:     { <<: *scanner-base, variables: { SCAN_TOOL: syft } }
scan:trufflehog:
  <<: *scanner-base
  before_script: [git fetch --unshallow || true]
  variables: { SCAN_TOOL: trufflehog }

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

What success looks like

  • Pipeline run completes with exit code 0 for all four scanner tools.
  • 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