BLACKSHIELD

Guía pública

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. Audiencia: DevOps engineers, platform engineers, and security engineers. Tiempo típico de configuración: 2 minutes.

Empieza aquíjourney

Úsalo si

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

Empieza aquí

Step 3 of 6

Recomendado
1
2
3
4
5
6

Antes de comenzar

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

Haz esto ahora

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

Cómo se ve el éxito

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

Open API Keys · Requiere inicio de sesión

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

Cómo se ve el éxito

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

All Deployment Guides

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

Cómo se ve el éxito

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

View Findings · Requiere inicio de sesión

Obtén el bundle de código fuente

Descarga los archivos exactos usados en esta guía o ejecuta el instalador de un solo comando para escribirlos localmente antes del despliegue.

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)
Descargar fuente

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)
Descargar fuente

Ejecuta esto

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

Cómo se ve el éxito

  • 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 | Docs de BlackShield