BLACKSHIELD

Guia público

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. Público: DevOps engineers, platform engineers, and security engineers. Tempo típico de configuração: 2 minutes.

Comece aquijourney

Use isto se

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

Comece aqui

Step 3 of 6

Recomendado
1
2
3
4
5
6

Antes de começar

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

Faça isto agora

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.

Como é o sucesso

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

Open API Keys · Requer login

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

Como é o sucesso

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

All Deployment Guides

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.

Como é o sucesso

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

View Findings · Requer login

Obtém o bundle de código fonte

Descarrega os ficheiros exatos usados neste guia ou executa o instalador de um só comando para os escrever localmente antes do deploy.

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)
Descarregar fonte

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)
Descarregar fonte

Executar isto

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

Como é o sucesso

  • 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 | Documentação BlackShield