BLACKSHIELD

Guía pública

Ingiere tus primeros hallazgos

Ejecuta un primer escaneo, envía hallazgos normalizados y verifica que la deduplicación y los metadatos se vean correctos en la plataforma. Audiencia: Ingenieros de seguridad y responsables de CI. Tiempo típico de configuración: 10-15 minutos.

Antes de comenzar

  • Cree una clave API de ingesta en /api-keys y guarde la clave sin formato (se muestra una vez).
  • Use imagen del escáner secplatform/pipeline-scanner:latest (o su alias public.ecr.aws reflejado).
  • Establezca SECPLATFORM_API_URL en su punto final de backend (local: http://localhost:8000).

Paso a paso

Paso 1

Ejecuta un escáner sobre un objetivo conocido

Usa un objetivo determinístico en tu primera ingesta para validar fácilmente los resultados esperados.

  • Ejecuta Trivy o Semgrep sobre un repositorio o imagen conocida.
  • Exporta resultados en formato JSON aceptado por el cliente.
  • Conserva metadatos de artefacto y rama para troubleshooting posterior.

Paso 2

Envía resultados por el cliente de ingesta

Usa la API key de tu tenant y envía los resultados mediante el cliente de escaneo correspondiente.

  • Configura URL y API key por variables de entorno.
  • Ejecuta el entrypoint del cliente que corresponde a la salida de tu escáner.
  • Guarda logs de respuesta como evidencia de payloads aceptados.

Paso 3

Valida la calidad de la ingesta

Confirma que los hallazgos existen, que el mapeo de severidad es consistente y que envíos repetidos no duplican problemas.

  • Abre Hallazgos y filtra por escáner y recurso objetivo.
  • Verifica que los campos first_seen y last_seen estén poblados.
  • Reenvía el mismo payload y confirma el comportamiento de deduplicación.

Ejecuta esto

Cree una clave API de ingesta a través de 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}'

Ejecute el primer análisis de canalización e incorpore los hallazgos

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

Comprobaciones de éxito

  • El estado del trabajo de ingestión llega a completado con creado > 0 o actualizado > 0.
  • Aparecen nuevos hallazgos en /findings con gravedad, análisis de origen y marcas de tiempo.
Ingiere tus primeros hallazgos | Docs de BlackShield