SAFE

SAFE realiza una evaluación de seguridad controlada y consciente del repositorio de los hallazgos de Semgrep y Trivy en artefactos de investigación.

Admite dos tareas de clasificación independientes: predicción directa binaria (SECURITY_RELEVANT o NON_SECURITY) y la taxonomía contextual detallada multiclase (tres etiquetas — ver Tres etiquetas). Cada tarea puede ejecutarse en modo zero-shot o agéntico.

Solo espera:

1. Un CSV de hallazgos delimitado por punto y coma.
2. Un directorio que contenga una carpeta de artefacto de investigación por cada artifact_id.
3. Opcionalmente, una colección de PDF/texto de artículos claveada por artifact_id.
4. Una clave API de OpenAI o acceso a un proxy LiteLLM de la organización.

No se entrena ni se ajusta con ningún dato de evaluación etiquetado. Los datos etiquetados se usan solo después de la inferencia, para evaluar predicciones, y nunca los ve el clasificador. SAFE nunca ejecuta código de artefactos; el texto del repositorio se trata como evidencia no confiable, no como instrucciones.

Esta versión contiene el código fuente completo de safe_audit, la CLI y las pruebas, además de un demo/ autocontenido con tres artefactos de ejemplo totalmente sintéticos que puedes ejecutar de principio a fin sin ningún dato externo. Excluye el corpus real de artefactos de investigación, las etiquetas de verdad fundamental y los hallazgos de evaluación utilizados en el artículo.

Inicio rápido: después de la Instalación, ejecuta la Demo — funciona de inmediato sin configuración de datos. config.example.yaml, cubierto más adelante en Configuración, es una plantilla para tus propios hallazgos/artefactos y no se ejecutará hasta que lo edites.

Instalación

cd path/to/safe-artifact-auditor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Establece la clave API:

export OPENAI_API_KEY="your-key"

Para un proxy LiteLLM de la organización, usa config.litellm.example.yaml en su lugar — está comentado en línea. Las credenciales y los valores de encabezados personalizados se leen de variables de entorno y nunca se almacenan en la configuración de SAFE ni en archivos de resultados.

Demo

demo/ contiene tres artefactos de ejemplo pequeños y totalmente sintéticos — ninguno derivado de ni correspondiente a ningún artefacto de investigación publicado real — uno por etiqueta de taxonomía, para que los revisores puedan ejercitar el pipeline completo sin ningún dato externo:

• demo-contextual-risk/ — un agregador de checkpoints de aprendizaje federado de juguete que deserializa un checkpoint descargado de una URL proporcionada por el llamador con torch.load. Entrada no confiable y proveniente de la red alcanza un sumidero de deserialización inseguro, que se espera que SAFE clasifique como CONTEXTUAL_RISK.
• demo-hardening-recommendation/ — un harness de benchmark de juguete que ejecuta subprocess.run(..., shell=True) contra líneas de comando que son todas literales de Python codificadas, sin entrada controlada por el llamador. Se espera que SAFE clasifique esto como HARDENING_RECOMMENDATION: el patrón de shell es real y vale la pena señalarlo, pero nada externo puede alcanzarlo o influenciarlo.
• demo-false-positive/ — un generador de fixtures de prueba fijado a una versión anterior de Pillow con un aviso hipotético de bomba de descompresión. El código solo crea nuevas imágenes en memoria y nunca abre datos externos, por lo que la ruta de código real del aviso nunca se alcanza. Se espera que SAFE clasifique esto como FALSE_POSITIVE.

demo/findings.csv contiene un hallazgo por artefacto, y demo/demo-zero-shot.yaml / demo/demo-agentic.yaml son configuraciones listas para ejecutar (artifact_root: . se resuelve relativo al archivo de configuración, así que ejecuta desde dentro de demo/):

cd demo
safe-audit run --config demo-zero-shot.yaml
safe-audit run --config demo-agentic.yaml

Los resultados se guardan en demo/runs/demo-zero-shot/ y demo/runs/demo-agentic/ respectivamente (ver Salida).

Tres etiquetas

• CONTEXTUAL_RISK
• HARDENING_RECOMMENDATION
• FALSE_POSITIVE

No se usa ninguna categoría adicional ni ninguna regla determinista de cambio de etiqueta. Un mecanismo de investigación/seguridad documentado y aislado en el código propio del artefacto se clasifica como HARDENING_RECOMMENDATION, ya que la práctica subyacente sigue siendo real incluso cuando el aislamiento limita la explotabilidad realista.

Clases binarias

• SECURITY_RELEVANT: un riesgo contextual válido o una preocupación de endurecimiento, incluido el comportamiento intencional y aislado de investigación de seguridad.
• NON_SECURITY: un hallazgo falso, no coincidente, no aplicable, ausente o de característica afectada demostrablemente no utilizada.

El evaluador también deriva una vista binaria de las predicciones multiclase: FALSE_POSITIVE se convierte en NON_SECURITY; cualquier otra etiqueta multiclase se convierte en SECURITY_RELEVANT. Los resultados binarios directos y derivados permanecen explícitamente separados.

Estructura de entrada

project/
├── config.yaml
├── data/
│   └── findings.csv
└── artifacts/
    ├── artifact_001/
    ├── artifact_002/
    └── artifact_003/

El mapeo es exacto: artifact_id = artifact_001 se resuelve a artifacts/artifact_001/.

Columnas CSV requeridas:

artifact_id;tool;finding_id

Columnas opcionales:

artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable

Una columna de índice inicial sin nombre se ignora. Las columnas adicionales se conservan mediante el modelo de entrada.

Ejemplo:

artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable
artifact_001;semgrep;python.lang.security.audit.subprocess-shell-true;code;HIGH;src/probe.py;42;Shell command uses shell=True;;;;CWE-78;;yes
artifact_002;trivy;DEMO-CVE-0001;dependency;HIGH;;;Affected package (illustrative, not a real CVE);example-lib;1.2.0;CWE-502;8.1;yes

Generar hallazgos desde un nuevo código base

scripts/run_scanners.py y scripts/build_findings_csv.py producen el findings.csv y la disposición de artefactos descrita anteriormente directamente desde tu propio código, usando Semgrep y Trivy.

Instala Semgrep (funciona igual en cualquier sistema operativo, incluido Linux):

pip install semgrep

Instala Trivy en Linux — ya sea el repositorio apt (Debian/Ubuntu):

sudo apt-get install wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy

o el script de instalación oficial, que funciona en cualquier distribución de Linux e instala una versión binaria en /usr/local/bin (no se requieren paquetes raíz más allá de sudo para ese directorio):

curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo sh -s -- -b /usr/local/bin

Verifica que ambos estén en PATH antes de continuar:

semgrep --version
trivy --version

Luego organiza un directorio por artefacto bajo un artifact_root/ y ejecuta:

python scripts/run_scanners.py artifact_root --output scan-output
python scripts/build_findings_csv.py scan-output --output data/findings.csv