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.

Before You Begin

  • Create an ingestion API key in /api-keys and save the raw key (shown once).
  • Use scanner image secplatform/pipeline-scanner:latest (or your mirrored public.ecr.aws alias).
  • Set SECPLATFORM_API_URL to your backend endpoint (local: http://localhost:8000).

Step-by-step

Step 1

Choose scanner image and first target

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

  • Use `secplatform/pipeline-scanner:latest` (or your mirrored public ECR alias) 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.

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 `SECPLATFORM_API_URL` and `SECPLATFORM_API_KEY` via environment variables.
  • Run the matching scanner client entrypoint or container command.
  • Capture response logs as proof of accepted payloads.

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.

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 SECPLATFORM_API_URL=http://localhost:8000 \
  -e SECPLATFORM_API_KEY=sp_your_key_here \
  -e SCAN_TOOL=trivy \
  -e SCAN_TARGET=python:3.11-slim \
  secplatform/pipeline-scanner:latest

Success Checks

  • 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