BLACKSHIELD

Public Guide

Ingest Your First Findings

Run your first scan, submit findings, and confirm data quality before expanding to more integrations. Audience: Security engineers, CI owners, and integration engineers. Typical setup time: 10-15 minutes.

Start herejourney

Use this if

Run your first scan, submit findings, and confirm data quality before expanding to more integrations.

Audience
Security engineers, CI owners, and integration engineers
Typical time
10-15 minutes

Start here

Step 4 of 6

Recommended
1
2
3
4
5
6

Before You Begin

  • Create an ingestion API key in /api-keys and save the raw key (shown once).
  • Use scanner image public.ecr.aws/blackshield-security/pipeline-scanner:1.0.0 to ingest your first findings.
  • Set BLACKSHIELD_API_URL to your backend endpoint (local: http://localhost:8000).

Do this now

Step 1

Choose scanner image and first target

Use a deterministic target and a known scanner image so results are easy to validate.

  • Use `public.ecr.aws/blackshield-security/pipeline-scanner:1.0.0` for first run.
  • Pick a known target such as `python:3.11-slim` for predictable first results.
  • Run Trivy or Semgrep in JSON mode supported by the scanner client.
  • Keep branch, commit, or artifact metadata for troubleshooting.

What success looks like

Keep branch, commit, or artifact metadata for troubleshooting.

Deploy the Pipeline Scanner

Step 2

Create and use an ingestion API key

Create a workspace key in API Keys and use it only for scanner ingestion.

  • Open `/api-keys`, create a key, and save the raw `sp_...` value immediately.
  • Set `BLACKSHIELD_API_URL` and `BLACKSHIELD_API_KEY` via environment variables.
  • Run the matching scanner client entrypoint or container command.
  • Capture response logs as proof of accepted payloads.

What success looks like

Capture response logs as proof of accepted payloads.

Open API Keys · Sign-in required

Step 3

Validate quality and deduplication

Ensure findings are complete, severity is mapped correctly, and repeated uploads do not duplicate issues.

  • Open Findings and filter by scanner and resource.
  • Verify `first_seen` and `last_seen` fields are populated.
  • Resubmit the same payload once and verify deduplication behavior.

What success looks like

Resubmit the same payload once and verify deduplication behavior.

Open Findings · Sign-in required

Run This

Create an ingestion API key via API

bash
TOKEN=$(curl -s -X POST "http://localhost:8000/api/v1/auth/login?email=admin@acme.com&password=changeme123" | python3 -c "import sys, json; print(json.load(sys.stdin)['access_token'])")

curl -s -X POST http://localhost:8000/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Pipeline Scanner","expires_in_days":90}'

Run first pipeline scan and ingest findings

bash
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e BLACKSHIELD_API_URL=http://localhost:8000 \
  -e BLACKSHIELD_API_KEY=sp_your_key_here \
  -e SCAN_TOOL=trivy \
  -e SCAN_TARGET=python:3.11-slim \
  public.ecr.aws/blackshield-security/pipeline-scanner:1.0.0

What success looks like

  • Ingestion job status reaches completed with created > 0 or updated > 0.
  • New findings appear in /findings with severity, source scanner, and timestamps.
Ingest Your First Findings | BlackShield Docs