Guía pública

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

Empieza aquíjourney

Úsalo si

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 engineersTypical time: 2 minutes

Empieza aquí

Step 4 of 7

Recomendado
1
2
3
4
5
6
7

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

1

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
2

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

Cómo se ve el éxito

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

Scanner Licensing Defaults
3

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

Solo demostración

Esta configuración está diseñada para facilitar el uso. Para desplegar clientes de escaneo a escala, planifique su arquitectura de despliegue en consecuencia o contáctenos para obtener las mejores prácticas empresariales.

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` 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.9 \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/github-security-scan.sh)
Descargar fuente

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

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.9 \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/bitbucket-pipelines.sh)
Descargar fuente

Ejecuta esto

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

Cómo se ve el éxito

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

Continúa

Keep your rollout moving with the next recommended step.

Ingiere tus primeros hallazgos
Deploy the Pipeline Scanner | Docs de BlackShield