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.

Antes de comenzar

  • Create an ingestion API key in Settings → API Keys with Ingestion scope only.
  • Confirm your CI runner can pull images from ghcr.io and reach your API URL.
  • For TruffleHog secret scanning: ensure fetch-depth: 0 is set in your checkout step.

Paso a paso

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 SECPLATFORM_API_KEY as a masked CI secret and SECPLATFORM_API_URL as a CI variable.

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.

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.

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
bash <(curl -fsSL https://stg-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 and schedule support.

.gitlab-ci.yml
bash
bash <(curl -fsSL https://stg-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 SECPLATFORM_API_URL="${{ vars.SECPLATFORM_API_URL }}" \
            -e SECPLATFORM_API_KEY="${{ secrets.SECPLATFORM_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" \
            ghcr.io/your-org/secplatform-pipeline-scanner:latest

GitLab CI — all four scanners

yaml
variables:
  SECPLATFORM_API_URL: "https://api.yourdomain.com"
  # SECPLATFORM_API_KEY: set in CI/CD → Variables (masked)

.scanner-base: &scanner-base
  stage: security
  image: ghcr.io/your-org/secplatform-pipeline-scanner:latest
  script: [python /app/entrypoint.py]
  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 SECPLATFORM_API_URL=https://api.yourdomain.com \
  -e SECPLATFORM_API_KEY=sp_xxxx \
  -e SCAN_TOOL=trivy \
  -e SCAN_TARGET=/workspace \
  -e SCAN_INTERVAL_SECONDS=0 \
  -v "$(pwd):/workspace:ro" \
  ghcr.io/your-org/secplatform-pipeline-scanner:latest

Comprobaciones de é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