bitcoin-custody-audit — auditoría de custodia Bitcoin en 14 etapas

Hermano de dominio de security-audit (12 capas). Aquel audita el repositorio: dependencias, CVE, SAST, contenedor, secretos. Este audita la custodia: de dónde vienen las claves, qué las puede romper y si la instalación que las vigila está bien puesta.

No se solapan: se encadenan. En un repositorio de custodia conviene correr los dos, y este declara explícitamente qué hereda de aquel.

Las tres reglas que gobiernan el skill

1. La cobertura se declara siempre. Lo que no se pudo comprobar aparece como no comprobado. Un «0 hallazgos» sobre una superficie que no se miró es una mentira con formato de informe.
2. Una etapa que no puede ejecutarse sale OMITIDA, no verde. Sin inventario, sin git o sin configuración son motivos legítimos para omitir; ninguno lo es para aprobar.
3. La ausencia de dato es un hallazgo. No poder demostrar con qué firmware nació una clave es el problema, aunque la clave esté sana.

[!IMPORTANT] Este skill nunca pide, lee ni acepta material secreto. No hay una sola ruta de código que consuma una semilla, una clave privada o una passphrase: el inventario son metadatos (fabricante, modelo, firmware, quorum), jamás claves. Si el skill encuentra material secreto en el repositorio, lo reporta como hallazgo — no lo usa.

Las 14 etapas

Bloque A — Las claves (1-3) · requieren inventario

Bloque B — El software (4-8) · sobre el repositorio

Bloque C — La instalación (9-13) · sobre la configuración versionada

Bloque D — Las personas (14)

Cómo se invoca

Desde la raíz del repositorio de custodia (trabaja sobre Path.cwd()):

# Las 14 etapas, informe por consola
python ~/.agents/skills/bitcoin-custody-audit/bitcoin_custody_audit.py

# Además, informe Markdown fechado en la raíz del repositorio
python ~/.agents/skills/bitcoin-custody-audit/bitcoin_custody_audit.py --report

# Solo algunas etapas (acepta rangos)
python ~/.agents/skills/bitcoin-custody-audit/bitcoin_custody_audit.py --stages 1,2,3,9-11

# Histórico completo en la etapa 5 (por defecto: últimos 2000 commits)
python ~/.agents/skills/bitcoin-custody-audit/bitcoin_custody_audit.py --deep

# Salida procesable · exit 1 también si alguna etapa quedó OMITIDA
python ~/.agents/skills/bitcoin-custody-audit/bitcoin_custody_audit.py --json --strict

El inventario de custodia

Las etapas 1-3 (y parte de la 6 y la 14) necesitan un inventario. Es metadatos, no claves. JSON funciona sin dependencias; YAML requiere pyyaml.

{
  "advisories_reviewed": "2026-08-01",
  "runtime_advisories_reviewed": "2026-08-01",
  "roles": {
    "aprueba_mover_fondos": "dos de los tres titulares, presencialmente",
    "custodia_firmante_c": "caja de seguridad bancaria"
  },
  "wallets": [
    {"id": "tesoreria", "quorum": "2-de-3", "value_tier": "high",
     "signers": ["cc-a", "tz-b", "led-c"]}
  ],
  "signers": [
    {"id": "cc-a", "vendor": "coldcard", "model": "Mk4",
     "firmware_at_seed": "5.1.2", "seed_created": "2024-03-11",
     "entropy_source": "device"}
  ],
  "advisories": [
    {"id": "CC-2023-01", "vendor": "coldcard", "models": ["Mk3"],
     "firmware_affected": "<4.1.0", "severity": "high",
     "url": "https://ejemplo.invalid/aviso"}
  ]
}

firmware_affected acepta <4.1.0, >=1.2 <1.5, ==2.0, listas y all. Si el firmware del firmante o el rango del aviso no permiten decidir, el cruce sale como W-PROV-INDECIDIBLE — nunca como «no afectado».

Qué produce

Una línea por etapa (OK, !! atención, XX fallo, .. omitida) con su cobertura y sus hallazgos; y, con --report, un SECURITY_AUDIT_BITCOIN_<fecha>.md con resumen, tabla de etapas, hallazgos por etapa, plan de remediación deduplicado y una sección final que enumera lo que el informe no dice (las etapas omitidas y por qué).

Códigos: los que empiezan por F- son fallos (exit 1); los W- describen deuda y no tumban el proceso.

Cuándo invocarlo

• Al cambiar el inventario: una wallet o un firmante nuevo cambia el mapa.
• Al publicar un aviso un fabricante que usas.
• Antes de cada release (etapas 4 a 8 y 13 son parte del checklist).
• Al cambiar la configuración del despliegue (etapas 9 a 11).
• Periódicamente, aunque no cambie nada: la etapa 2 detecta que el mundo cambió aunque tu repositorio no.

Relación con security-audit

Orden natural: primero security-audit sobre el repositorio, después bitcoin-custody-audit sobre la custodia y la instalación. La etapa 7 se apoya en el mismo razonamiento que python-deps-pinning: sin lockfile no hay versión que consultar.

Limitaciones

• No verifica la procedencia que le cuentas. Si alguien registra un firmware incorrecto, el diagnóstico será incorrecto. Ningún programa puede comprobar qué firmware tenía un dispositivo hace dos años.
• La matriz de avisos es manual y local. El skill detecta que está vieja; no la actualiza, y no accede a la red.
• La etapa 4 es estática. Lee el código, no ejecuta la aplicación: la versión fuerte de esa comprobación se hace contra la app en marcha, antes del release.
• La etapa 5 no confirma frases mnemónicas. Detecta la forma (12/15/18/21/24 palabras seguidas) sin la wordlist BIP39, así que sale como heurística para revisar a mano, nunca como certeza.
• No mira la cadena. Sin análisis de UTXO, de reutilización de direcciones ni de contrapartes: es una decisión de alcance, no una carencia.
• No sustituye una auditoría criptográfica ni un proceso profesional de respuesta a incidentes.
• Las etapas 9-11 leen la configuración versionada, no procesos en ejecución.