> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockgence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Auditoría

> Revisión de smart contracts con agentes de IA: la IA propone y la ejecución prueba. Niveles, grados de validación, pistas, informe y sello.

> [!WARNING]
>
> **Auditoría está en vista previa.** El motor de agentes todavía no corre de punta a punta en el servicio. Lo que hoy
> ves en la app:
>
> * Las auditorías del dashboard son **de ejemplo**: proyectos, repos, contratos y hallazgos **sintéticos**, marcados con
>   «datos de ejemplo». Sirven para conocer las pantallas. No son auditorías reales.
> * Una revisión que pedís **queda registrada en cola, pero no corre**. La pantalla lo dice y sus secciones quedan vacías:
>   eso no quiere decir «sin hallazgos».
> * La verificación del bytecode desplegado y la publicación del sello todavía no están disponibles.
>
> El resto de esta página describe cómo funciona el producto y qué va a mostrar cada sección.

Auditoría revisa los smart contracts de un repositorio en un commit fijo. Agentes de IA especializados proponen
hipótesis de ataque, y un hallazgo cuenta solo con su prueba: un test que reproduce el ataque, un invariante roto, la
confirmación de una persona o un dato determinista. Lo que no se pudo probar se muestra aparte, como **pista**, sin
severidad.

Se entra desde **app.blockgence.com → Auditoría**.

![Dashboard de Auditoría](https://mintcdn.com/blockgence/jIDqBW86tOU_Ini-/images/products/audit/dashboard.png?fit=max\&auto=format\&n=jIDqBW86tOU_Ini-\&q=85\&s=5381584374cc1bd39812c2d3b5d26f27)

El dashboard de auditorías, con las auditorías de ejemplo.

## Niveles

| | **Revisión automática** | **Revisión asistida** | **Auditoría** |
| - | - | - | - |
| Entrada | Repo y commit | Repo, commit y tests que pasan | Repo, commit, especificación y una reunión de arranque |
| Humano | No | Triage corto de los hallazgos | Un auditor de punta a punta |
| Qué incluye | Mapa del código, análisis estático y checklist de preparación | El motor entero: especialistas, escéptico, pruebas de concepto, invariantes y fuzzing | Todo, manejado por el auditor |
| Informe | Privado | Privado; se puede publicar | Público si querés |
| Sello | No | Sí, si se publica | Sí |

La palabra «auditoría» nombra solo lo que revisa una persona. La revisión automática no lo es.

## Grados de validación

Cada hallazgo dice **qué lo prueba**. El grado lo asigna una regla fija, no un agente.

| Grado | Qué lo respalda |
| - | - |
| **G1 · Probado por ejecución** | Una prueba de concepto de Foundry que pasa en el sandbox, con un oráculo explícito: el atacante gana, se rompe un invariante o alguien sin permiso cambia un estado. Se descarga como test. |
| **G2 · Probado por fuzzing o ejecución simbólica** | Un invariante roto, con la secuencia de llamadas reducida, o un contraejemplo. |
| **G3 · Confirmado por revisión** | Una persona lo confirma con una cita, y el escéptico no lo pudo refutar. |
| **G4 · Hecho determinista** | Una regla o herramienta con coincidencia exacta y cita, o un dato on-chain (por ejemplo, el upgrade lo controla una cuenta común). |
| **Pista** | Una hipótesis sin prueba. Va aparte, en **Pistas sin validar**, sin severidad y fuera del conteo. |

**Origen** (quién lo propuso: un agente, una regla, una herramienta, una persona) y **grado** (qué lo prueba) son dos
cosas distintas: una hipótesis de un agente con una prueba que pasa es G1.

### Severidad

Crítica, Alta, Media, Baja, Informativa y Gas.

* Crítica y Alta exigen G1, G2 o G3. Un hallazgo G4 sobre el código no pasa de Media.
* Los avisos de control sobre lo desplegado son G4 con una severidad fija (ver «Deploy y control»).
* Una pista no lleva severidad. Muestra la severidad que tendría si se probara, para saber dónde mirar.
* Un hallazgo que marcás como reconocido conserva su severidad.

## Una auditoría por dentro

Cada auditoría es un espacio aislado, como un caso: lo que hay adentro pertenece a esa auditoría y a tu organización.
Arriba van el proyecto, el repo y el commit, el nivel y el estado de la corrida. Debajo, sus secciones:

> [accordion] Resumen, Hallazgos, Pistas y Pruebas
>
> * **Resumen:** el conteo por severidad y grado, qué cubrió y qué no, y los descargos.
> * **Hallazgos:** cada uno con su grado, su ubicación (archivo y línea), el código resaltado, la descripción, el
>   impacto, la recomendación y su prueba o cita.
> * **Pistas:** las hipótesis sin validar, con la severidad posible, en cuántas corridas aparecieron, la refutación del
>   escéptico si la hay y por qué no se probaron.
> * **Pruebas:** las pruebas de concepto y las secuencias de fuzzing, con la salida de Foundry y los saldos antes y
>   después.

> [accordion] Mapa, Amenazas, Invariantes, Corrida y Revisiones
>
> * **Mapa:** contratos, herencia, puntos de entrada con sus guardas, roles, flujos de valor y llamadas externas, en un
>   diagrama navegable.
> * **Amenazas:** el modelo de amenazas: activos, actores, dependencias, qué sería catastrófico y qué familias de ataque
>   se buscaron (y cuáles no, con el porqué).
> * **Invariantes:** las propiedades, con su estado: rota (con la secuencia), no se rompió, en verificación o no se
>   ejercitó.
> * **Corrida:** las etapas y los agentes, el presupuesto usado, el modelo y las habilidades de cada agente, los tokens
>   y el costo.
> * **Revisiones:** el historial por commit y la comparación entre dos corridas: corregidos, nuevos y los que siguen.

> [accordion] Deploy y control, Sello y Notas
>
> * **Deploy y control:** las direcciones desplegadas, la verificación del bytecode contra el commit y el informe de
>   control.
> * **Sello:** publicar el informe, el estado vivo del sello y cómo se verifica la firma.
> * **Notas:** las anotaciones de tu equipo sobre hallazgos y pistas.

![Sección Hallazgos](https://mintcdn.com/blockgence/jIDqBW86tOU_Ini-/images/products/audit/findings.png?fit=max\&auto=format\&n=jIDqBW86tOU_Ini-\&q=85\&s=c2cdc2f53b08f9b3d5cd9189029c399d)

Hallazgos de una auditoría de ejemplo.

Parcial y Falló se muestran en ámbar con su causa: es una etapa que no corrió, no un riesgo. **Lo que no corrió no se
revisó**, y eso no es «sin hallazgos».

## Pedir una revisión

**1. El código**

Un repo **público de GitHub** y el **hash completo del commit** (40 caracteres): todo el informe refiere a ese commit,
no a una rama. Subir un zip y los repos privados todavía no están disponibles.

**2. Los archivos en alcance**

Por defecto entra `src/` sin tests, scripts ni dependencias. Se edita una línea por camino o patrón, y con `!` adelante
se excluye. Lo que queda afuera no se revisa, y el informe lo dice.

**3. El nivel y la especificación**

Elegí el nivel. La especificación es opcional, salvo en Auditoría: con ella se pueden marcar las discrepancias entre lo
que el código hace y lo que debería hacer.

> [!NOTE]
>
> Hoy la revisión queda **en cola** y no corre (ver el aviso de arriba). Pedirla no cobra créditos.

## Deploy y control

Una auditoría es una foto de un commit. Después del informe, un contrato puede quedar expuesto si se despliega algo
distinto, si las claves o los roles quedan mal puestos, o si hay un upgrade. Esta sección cubre esas tres cosas:

* **Verificación del bytecode** contra el commit revisado: **coincide**, **coincide salvo metadata** o **no coincide**, con
  la primera diferencia. En un proxy se compara la implementación. *Todavía no disponible: una dirección que cargues queda
  «sin verificar».*
* **Informe de control**, a partir de la lectura de `/v1/contract`: quién puede actualizar el contrato (la cadena
  ProxyAdmin → Safe → timelock), quién tiene cada poder y estos avisos, con severidad fija:

| Aviso | Severidad |
| - | - |
| El upgrade lo controla una cuenta común | Alta |
| Safe con umbral 1, o con todos los firmantes iguales, y al menos un dueño que es una cuenta común | Alta |
| Timelock de 0 segundos | Media |

Un aviso sale solo de un **hecho** de la lectura. Lo que la lectura no puede decidir (un tope de emisión, un timelock que
el admin puede saltear, un rol renunciado que la especificación dice que existe) se declara como no evaluado.

## Informe y sello

**El informe es privado por defecto.** Si lo publicás, se genera el **sello**: una página pública con el informe, el
commit, las direcciones y su red, la firma de Blockgence y un sello de tiempo de OpenTimestamps. Las direcciones pasan a
vigilarse con Watchtower, y el sello cambia de estado:

| Estado | Cuándo |
| - | - |
| **Vigente** | El código y el control coinciden con lo revisado. |
| **Código cambiado** | Hubo un upgrade a una implementación que no se revisó. |
| **Control cambiado** | Cambió quién controla el contrato. No invalida el código, pero se avisa. |
| **Vencido** | Pasó el plazo de validez sin una revisión nueva. |

Cualquiera puede verificar el sello sin confiar en la web de Blockgence: bajar el informe, recalcular su sha256,
comprobar la firma con la clave pública y el sello de tiempo con OpenTimestamps. Ver
[Metodología y evidencia](https://docs.blockgence.com/es/methodology/verify-signature.md). *Publicar todavía no está disponible.*

![Sección Sello](https://mintcdn.com/blockgence/jIDqBW86tOU_Ini-/images/products/audit/seal.png?fit=max\&auto=format\&n=jIDqBW86tOU_Ini-\&q=85\&s=2b99005464feac250164feca5053c39e)

La sección Sello de una auditoría de ejemplo.

## Por API

| Método | Ruta | Qué hace |
| - | - | - |
| GET | `/v1/audit` | Las auditorías de tu organización y las de ejemplo (marcadas `demo: true`). |
| GET | `/v1/audit/{id}` | El resumen de una auditoría: corrida, conteos por severidad y grado, pistas y sello. |
| GET | `/v1/audit/{id}/{section}` | Una sección: `resumen`, `mapa`, `amenazas`, `hallazgos`, `pistas`, `invariantes`, `pruebas`, `corrida`, `revisiones`, `deploy`, `sello` o `notas`. |
| POST | `/v1/audit` | Pedir una revisión. Hoy queda en cola y la respuesta lo declara en `note` y `queue`. |
| POST | `/v1/audit/{id}/deploy` | Cargar las direcciones desplegadas de una red. |
| POST | `/v1/audit/{id}/notes` | Agregar una nota del equipo. |

```bash Pedir una revisión theme={null}
curl -X POST https://app.blockgence.com/v1/audit \
  -H "X-API-Key: $BKG_KEY" -H "Content-Type: application/json" \
  -d '{"repo": "https://github.com/ejemplo/vault", "commit": "3f2a1c9e5b7d4a06c1e8f2b39d0a7c5e1f4b6a28", "level": "automated"}'
```

```json Respuesta (recortada) theme={null}
{
  "demo": false,
  "note": "El motor de auditoría no está encendido en este servidor: la revisión quedó registrada en cola, pero no va a correr hasta que se encienda. No hay resultados: las secciones vacías no son «sin hallazgos».",
  "audit_id": "aud_20a6e106dc7ab5cf",
  "audit": { "id": "aud_20a6e106dc7ab5cf", "repo": "ejemplo/vault", "level": "automated",
             "run": { "state": "queued" }, "requested": true, "findings_total": 0, "leads": 0 },
  "queue": { "state": "not_enqueued" }
}
```

Cada pedido sobre una auditoría acepta el header opcional `X-Audit-Id`. Si no coincide con la ruta, la respuesta es
`400 audit_id_mismatch`. Una auditoría de otra organización da el mismo `404` que una que no existe. Las rutas de
Auditoría no cobran créditos. Detalle en la [referencia de la API](https://docs.blockgence.com/es/api/reference.md).

## Qué no cubre

* **Una revisión no es una garantía de seguridad.** Cubre el commit y los archivos en alcance. Código, configuración,
  claves e integraciones fuera de ese alcance no se revisan.
* Las herramientas automáticas no detectan la mayoría de los errores de lógica de negocio.
* Los agentes de IA proponen. Un hallazgo cuenta solo con su prueba (G1 a G4). **Las pistas pueden ser falsas, y la
  ausencia de hallazgos no prueba que no haya bugs.**
* El informe dice qué modelo de IA se usó y qué cubrió cada agente.
* Watchtower solo ve lo que el contrato emite: el dueño de un ProxyAdmin o de un Safe que no se registró queda afuera.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.