AuditAgent Toolkit

Toolkit modular de auditoría técnica en Python. Solo biblioteca estándar. 19 módulos independientes. Contrato JSON uniforme.

¿Qué es?

AuditAgent Toolkit es un conjunto de herramientas modulares para auditar repositorios de código. Cada módulo:

• Tiene una sola responsabilidad.
• Usa solo la biblioteca estándar de Python.
• Produce JSON conforme a un contrato uniforme.
• Declara explícitamente sus limitaciones.
• Se puede ejecutar independientemente del resto.

¿Qué audita?

Área	Módulo	Qué detecta
Inventario	inventory	Archivos, directorios, symlinks, tamaños
Git	git_state	Estado, historial, remotos, identidades
Privacidad	sensitive_data	Secretos, correos, rutas (con redacción)
Escrituras	write_surface	APIs de escritura vía AST
Contratos	json_contracts	JSON válidos, esquemas, validadores
Pruebas	test_runner	Compilación y ejecución de tests
Inmutabilidad	readonly_immutability	Snapshots antes/después
Frontera de salida	output_boundary	Escrituras internas al repo
Symlinks	symlink_policy	Enlaces internos, externos, rotos
Ocultos	hidden_policy	include_hidden false/true
Exclusiones	exclusion_policy	.bak, .egg-info, __pycache__
Tamaños	size_limits	Límite-1, límite, límite+1
Binarios	binary_handling	NUL, UTF-8, bytes inválidos
Permisos	permission_handling	chmod 000
Determinismo	determinism	Dos ejecuciones, JSON normalizado
Atomicidad	atomic_output	Escritura atómica real
Coherencia	result_coherence	Comparación entre dos resultados
Puntuación	score_module	Score 0-100 por resultado
Informe	assemble_report	Markdown agregado

Instalación

Desde PyPI (próximamente)

pip install auditagent-toolkit

Desde el repositorio (desarrollo)

git clone https://github.com/mgonzalez88201-creator/auditagent-toolkit.git
cd auditagent-toolkit
pip install -e .

Requisitos

• Python 3.10 o superior.
• Cero dependencias externas.
• Funciona en Linux, macOS y Windows.

Quickstart

Listar módulos y perfiles

auditagent list

Ejecutar un módulo concreto

auditagent run inventory . --json-output /tmp/inventory.json

Ejecutar un perfil completo

auditagent profile rapid . --output-dir /tmp/audit-results

Perfiles disponibles:

• rapid: 6 módulos (inventario, git, privacidad, escrituras, contratos, pruebas).
• standard: 10 módulos (rapid + inmutabilidad, frontera, determinismo, coherencia).
• deep: 17 módulos (standard + symlinks, ocultos, exclusiones, límites, binarios, permisos, atomicidad).

Generar un informe

auditagent run assemble_report /tmp/audit-results/*.json --title "Auditoría" --output /tmp/audit-results/INFORME.md

Ejemplos

Auditar un repositorio local

auditagent profile standard /ruta/al/repo --output-dir /tmp/audit

Auditar solo secretos

auditagent run sensitive_data /ruta/al/repo --json-output /tmp/secrets.json

Auditar inmutabilidad de una CLI externa

auditagent run readonly_immutability /ruta/al/repo --request /tmp/request.json --command 'mi-cli scan --request {request} --output {output}' --json-output /tmp/readonly.json

Puntuar un resultado

auditagent run score_module /tmp/secrets.json --json-output /tmp/score.json

Contrato de salida

Todos los módulos devuelven JSON conforme a schemas/module_result.schema.json:

{
  "schema_version": "1.0",
  "module": "nombre",
  "status": "PASS | WARN | FAIL | NOT_RUN | ERROR",
  "confidence": "high | medium | low",
  "root": "/ruta/resuelta",
  "summary": {},
  "findings": [],
  "evidence": [],
  "limitations": [],
  "started_at": "2026-09-28T00:00:00+00:00",
  "finished_at": "2026-09-28T00:00:01+00:00"
}

Esto permite: comparar módulos, revisar un control, guardar evidencia reproducible, ensamblar informes sin re-ejecutar, integrar con CI/CD.

Principios de diseño

1. Solo stdlib. Nunca dependencias externas.
2. No escribe en el repo auditado. Solo en --json-output.
3. Cada módulo es independiente. No requiere que otros se ejecuten antes.
4. Contrato uniforme. Todos respetan el mismo schema.
5. Limitaciones explícitas. Cada módulo declara qué NO cubre.
6. Redacción de datos sensibles. Nunca imprime valores coincidentes.
7. Honestidad sobre evidencia. Si el entorno invalida un caso, lo declara.

Estructura del proyecto

auditagent-toolkit/
├── LICENSE                    Apache 2.0
├── NOTICE                     Atribución
├── README.md                  Este archivo
├── CHANGELOG.md               Historial de versiones
├── INDEX.md                   Documentación de módulos
├── VALIDATION.md              Historial de validación
├── pyproject.toml             Metadata del paquete
├── auditagent_manifest.json   Perfiles rapid/standard/deep
├── validate_toolkit.py        Validador de sintaxis
├── SHA256SUMS.txt             Checksums de integridad
├── auditagent_tools/          19 módulos + cli.py
├── examples/                  Plantillas y casos de uso
└── schemas/                   JSON Schema del contrato

Limitaciones conocidas

• Los módulos dinámicos requieren una CLI externa y una plantilla de comando.
• La extracción de rutas busca campos llamados path en JSON.
• La detección de secretos es heurística (regex, sin entropía).
• No sustituye aislamiento del sistema operativo.
• No demuestra ausencia de carreras TOCTOU.

Ver VALIDATION.md para el historial de pruebas realizadas.

Desarrollo

Ejecutar validación

python validate_toolkit.py

Compilar todos los módulos

python -m py_compile auditagent_tools/*.py

Contribuciones

Aún no se aceptan contribuciones externas. Cuando se abra el proyecto, se publicará una guía de contribución.

Licencia

Apache License 2.0 — ver LICENSE y NOTICE.

Autor

Mago — @mgonzalez88201-creator

Estado

Versión 0.2.0 — alpha. Funcional pero sin tests propios ni CI.

Enlaces

• Documentación de módulos
• Historial de validación
• Changelog
• Manifest de perfiles
• Contrato JSON