Skip to content

datanicaragua/ai-cli-sentinel

BranchesTags

Repository files navigation

AI-CLI-Sentinel

PowerShell Linting

Sistema de seguridad para monitoreo y protección de interfaces de línea de comandos con capacidades de IA.

¿Por qué necesito AI-CLI-Sentinel?

Si usas herramientas de inteligencia artificial en tu terminal (como Gemini, Claude, Codex o GitHub Copilot), necesitas mantenerlas actualizadas para obtener las últimas mejoras. Sin embargo, actualizar software desde internet puede ser riesgoso. AI-CLI-Sentinel es tu "cinturón de seguridad": automatiza la actualización de tus agentes favoritos asegurándose de que, si algo sale mal o el paquete contiene errores, tu computadora y tus llaves de acceso (API Keys) estén protegidas.

✅ Checklist de Confianza

¿Qué hace este script por mí?

  • ✅ No toca tus archivos personales: Solo respalda configuraciones de IA.
  • ✅ Es reversible: Crea un punto de restauración para que puedas "volver atrás".
  • ✅ Es silencioso: Hace el trabajo pesado en segundos sin pedirte configuraciones complejas.
  • ✅ Solo actualiza lo que tú apruebas: Trabaja con una lista blanca estricta de agentes confiables.
  • ✅ Protege tus secretos: Respalda automáticamente tus llaves de acceso antes de cualquier cambio.

🤖 Agentes Soportados

AI-CLI-Sentinel gestiona de forma segura los siguientes agentes de IA:

Agente Desarrollador Gestor Propósito
Gemini CLI Google npm Asistente multimodal y generación de código.
Claude Code Anthropic npm Programación en pareja (Pair programming) avanzada.
Codex CLI OpenAI npm Generación de comandos y lógica de programación.
Qwen Code Alibaba npm Modelos de lenguaje especializados en código.
GitHub Copilot CLI GitHub npm Asistencia de IA para comandos y flujos en terminal.
Aider Aider uv tool Asistente para desarrollo de código asistido por IA en terminal.

Nota: En operación elevada, la lista blanca aprobada debe vivir en %ProgramData%\AI-CLI-Sentinel\policy\agents.allowlist.json. El archivo src/agents.allowlist.json queda como fallback del repositorio y activará una advertencia de seguridad.

🚀 Características

  • Seguridad primero: Solo actualiza agentes que tú explícitamente apruebas en tu lista blanca
  • Protección automática: Crea puntos de restauración antes de cualquier cambio
  • Respaldo de secretos: Guarda tus llaves de acceso solo en una ruta explícita y validada antes de actualizar
  • Modo descubrimiento: Encuentra agentes instalados que no están en tu lista blanca (sin hacer cambios)
  • Prevención de malware: Usa técnicas avanzadas para evitar la ejecución de código malicioso durante instalaciones
  • Registro completo: Mantiene un log detallado de todas las operaciones para tu revisión

📋 Requisitos

  • PowerShell 5.1 o superior (recomendado: PowerShell 7.4+)
  • Windows 10/11 o Windows Server 2016+
  • Privilegios de Administrador (requeridos para VSS y actualizaciones globales)
  • Node.js y npm instalados (para gestión de paquetes NPM)
  • Winget instalado (para gestión de aplicaciones Windows)
  • UV instalado (para gestión de herramientas Python tipo uv tool, como aider-chat)

🔧 Instalación

Instalación Rápida

# Clonar el repositorio
git clone https://github.com/datanicaragua/ai-cli-sentinel.git
cd ai-cli-sentinel

# Verificar estructura
Get-ChildItem -Recurse

Configuración Inicial

  1. Revisar configuración de fallback del repositorio:

    Get-Content src\agents.allowlist.json

  2. Instalar la raíz de confianza protegida:

    # Ejecutar como Administrador
New-Item -ItemType Directory -Path "$env:ProgramData\AI-CLI-Sentinel\policy" -Force
Copy-Item "src\agents.allowlist.json" "$env:ProgramData\AI-CLI-Sentinel\policy\agents.allowlist.json" -Force

  3. Personalizar lista de permitidos: Edita %ProgramData%\AI-CLI-Sentinel\policy\agents.allowlist.json para agregar tus agentes permitidos en los arrays npm, winget y uv. Usar src\agents.allowlist.json directamente solo es un fallback para desarrollo o arranque inicial y emitirá una advertencia de seguridad durante la ejecución.

  4. Verificar permisos:

    Get-ExecutionPolicy
# Si es necesario: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Política de Raíz de Confianza

AI-CLI-Sentinel prioriza la allowlist protegida en:

$env:ProgramData\AI-CLI-Sentinel\policy\agents.allowlist.json

Esta ruta debe ser administrada con ACLs de administradores y tratada como política de seguridad. Si el archivo no existe, el script cae de forma controlada a src\agents.allowlist.json, pero lo reporta como fallback inseguro para recordar que el repositorio local no debe ser la raíz de confianza de una ejecución elevada.

📖 Uso

Ejecución Estándar (Modo Seguro)

Actualiza solo los agentes en la lista blanca con respaldo de secretos:

# Ejecutar como Administrador
.\src\AI-CLI-Sentinel.ps1 -BackupSecrets -BackupPath "C:\SecureBackups"

-BackupSecrets requiere -BackupPath. Las rutas bajo Desktop, OneDrive u otras carpetas conocidas de sincronización en nube se bloquean por defecto para reducir el riesgo de exfiltración de credenciales.

Comportamiento funcional:

  • Primero compara la versión instalada contra la versión disponible.
  • Solo ejecuta la actualización cuando detecta una versión más reciente.
  • Genera un reporte JSON estructurado con el detalle antes -> después por agente, salvo que uses -NoReport.
  • Si no puede escribir el reporte JSON solicitado, la ejecución se considera fallida para no perder trazabilidad.

Comportamiento de salida:

  • Devuelve 0 cuando todas las operaciones completan sin fallos.
  • Devuelve 1 si una o más actualizaciones fallan (útil para automatización/CI).

Resumen esperado por estados:

  • updated: se instaló una versión más reciente.
  • would-update: hay una versión más reciente, pero la ejecución fue con -WhatIf.
  • already-current: el agente ya estaba al día.
  • not-installed: el agente está en allowlist, pero no está instalado localmente.
  • failed: hubo un fallo operativo al consultar o actualizar.
  • unknown: no se pudo determinar el estado final con certeza.

Modo Simulación (WhatIf)

Ver qué haría el script sin realizar cambios:

.\src\AI-CLI-Sentinel.ps1 -WhatIf

En este modo, los agentes con una versión más reciente disponible se reportan como would-update. No se escriben ni el archivo de log ni el reporte JSON para evitar efectos laterales.

Modo Descubrimiento (Auditoría)

Buscar agentes de IA instalados que NO están en la lista blanca:

.\src\AI-CLI-Sentinel.ps1 -Discover

Este modo NO realiza cambios de actualización. Exporta candidatos detectados en src\agents.candidates.json para revisión.

Aprobar Candidatos Detectados (Paso Explícito)

Revisar candidatos y decidir si se agregan a la lista blanca:

.\src\AI-CLI-Sentinel.ps1 -ApproveCandidates

Modo no interactivo (aprobación de todos los pendientes):

.\src\AI-CLI-Sentinel.ps1 -ApproveCandidates -AutoApproveCandidates

Este modo solo actualiza la allowlist. Luego ejecuta el flujo estándar para actualizar paquetes.

¿Qué comando debo usar?

  • Si quieres ver qué haría el script sin tocar nada: ./src/AI-CLI-Sentinel.ps1 -WhatIf
  • Si quieres detectar CLIs instalados fuera de tu allowlist: ./src/AI-CLI-Sentinel.ps1 -Discover
  • Si quieres revisar y aprobar candidatos detectados: ./src/AI-CLI-Sentinel.ps1 -ApproveCandidates
  • Si quieres ejecutar la actualización real con respaldo de secretos: ./src/AI-CLI-Sentinel.ps1 -BackupSecrets -BackupPath "C:\SecureBackups"

📘 Guía Rápida para Usuarios No Técnicos

¿Qué hace AI-CLI-Sentinel?

Imagina que tienes varios asistentes de IA instalados en tu computadora (como Gemini, Claude, Codex). Cada cierto tiempo, estos asistentes reciben actualizaciones con nuevas funciones y correcciones de errores. AI-CLI-Sentinel es como un asistente personal que:

  1. Verifica qué asistentes tienes instalados (modo Discover)
  2. Actualiza solo los que tú apruebas (lista blanca)
  3. Crea una copia de seguridad antes de hacer cambios (punto de restauración)
  4. Protege tus llaves de acceso en una ruta local explícita y no sincronizada

Línea de Tiempo del Proceso

┌─────────────────────────────────────────────────────────────┐
│ 1. Inicio: Verificas que tienes permisos de administrador  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. Preparación: Se crea un punto de restauración del sistema│
│    (por si necesitas "volver atrás")                        │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Respaldo: Se guardan tus llaves en BackupPath validado  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. Actualización: Se actualizan solo los agentes aprobados  │
│    en tu lista blanca                                       │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. Finalización: Todo listo. Tus agentes están actualizados  │
│    y protegidos                                              │
└─────────────────────────────────────────────────────────────┘

Modo Simulación (Recomendado para Primera Vez)

Antes de ejecutar el script por primera vez, usa el modo simulación para ver qué haría sin hacer cambios reales:

.\src\AI-CLI-Sentinel.ps1 -WhatIf

Verás mensajes como:

  • What if: Performing the operation 'Crear Punto de Restauración (VSS)'...
  • What if: Performing the operation 'Actualizar NPM'...

Esto te permite entender exactamente qué hará el script antes de ejecutarlo realmente.

Personalizar Archivo de Configuración

.\src\AI-CLI-Sentinel.ps1 -ConfigFile "ruta\personalizada\agents.allowlist.json" -BackupSecrets -BackupPath "C:\SecureBackups"

Personalizar Ruta de Logs

.\src\AI-CLI-Sentinel.ps1 -LogPath "C:\Logs\sentinel.log" -BackupSecrets -BackupPath "C:\SecureBackups"

Personalizar Ruta del Reporte JSON

.\src\AI-CLI-Sentinel.ps1 -ReportPath "C:\Logs\sentinel-report.json" -BackupSecrets -BackupPath "C:\SecureBackups"

Si la ruta indicada no es escribible y no usas -NoReport, el script terminará con error para evitar una ejecución sin evidencia estructurada.

Para desactivar el reporte estructurado en una ejecución puntual:

.\src\AI-CLI-Sentinel.ps1 -NoReport -BackupSecrets -BackupPath "C:\SecureBackups"

📁 Estructura del Proyecto

ai-cli-sentinel/
├── .github/
│   ├── workflows/
│   │   └── ci-lint.yml           # CI: Validación automática
│   └── ISSUE_TEMPLATE/
│       ├── bug_report.md
│       ├── feature_request.md
│       └── security_report.md
├── src/
│   ├── AI-CLI-Sentinel.ps1       # Script principal
│   └── agents.allowlist.json     # Fallback de configuración
├── tests/
│   └── AI-CLI-Sentinel.tests.ps1 # Pruebas unitarias
├── docs/
│   ├── architecture.md           # Arquitectura del sistema
│   └── recovery.md               # Guía de recuperación
├── .gitignore
├── CONTRIBUTING.md
├── LICENSE
├── README.md
└── SECURITY.md

🔄 Flujo de Ejecución

flowchart TD
    A[Inicio: AI-CLI-Sentinel] --> B{¿Privilegios<br/>Admin?}
    B -->|No| C[Error: Se requieren privilegios]
    B -->|Sí| D[Cargar allowlist protegida]
    D --> E{¿Modo<br/>Discover?}
    E -->|Sí| F[Buscar agentes instalados]
    F --> G[Reportar candidatos]
    G --> H[Fin: Solo reporte]
    E -->|No| I{¿WhatIf?}
    I -->|Sí| J[Mostrar acciones simuladas]
    J --> H
    I -->|No| K[Crear punto VSS]
    K --> L{¿Backup<br/>Secrets?}
    L -->|Sí| M[Respaldar secretos en BackupPath]
    L -->|No| N[Actualizar agentes NPM]
    M --> N
    N --> O[Actualizar aplicaciones Winget]
    O --> P[Fin: Actualización completa]
    
    style A fill:#e1f5ff
    style C fill:#ffcccc
    style H fill:#ccffcc
    style P fill:#ccffcc
Loading

🧪 Testing

Ejecutar tests desde terminal (runner robusto):

# Ejecutar tests (instala/usa Pester compatible automáticamente)
.\scripts\run-tests.ps1 -InstallPester5 -FailOnError

¿Cuándo correr tests?

  • Antes de abrir un Pull Request.
  • Después de cambios en src/AI-CLI-Sentinel.ps1.
  • Después de cambios en configuración o flujo de actualización (src/agents.allowlist.json, raíz de confianza protegida, control de errores, logging).
  • Después de atender comentarios de revisión o refactors en el script.

¿Para qué sirven estos tests?

  • Verifican que el script principal exista y mantenga parámetros esperados como -Discover, -BackupSecrets, -BackupPath y -ConfigFile.
  • Validan que la configuración JSON tenga estructura correcta.
  • Detectan regresiones básicas en sintaxis PowerShell, decisiones de seguridad y el nuevo contrato de actualización por versión/reporte estructurado.

Si solo vas a usar la herramienta y no estás modificando código, normalmente no necesitas ejecutar estos tests. Están orientados sobre todo a desarrollo, mantenimiento y validación antes de publicar cambios.

🔒 Seguridad

Para reportar vulnerabilidades de seguridad, por favor usa el formulario de seguridad o consulta SECURITY.md.

Referencias de Seguridad

Este proyecto implementa prácticas de seguridad basadas en estándares reconocidos:

  1. OWASP Top 10 para LLM (2024-2025)

    • Mitiga riesgos de "Insecure Output Handling" mediante validación estricta de entrada.
    • Previene ataques de inyección indirecta mediante lista blanca de agentes.
    • Referencia: OWASP LLM Top 10

  2. Node.js Security Best Practices

    • Utiliza --ignore-scripts para prevenir la ejecución de malware durante la instalación de paquetes npm.
    • Referencia: npm Security Best Practices

  3. Microsoft Volume Shadow Copy Service (VSS)

    • Implementa puntos de restauración del sistema antes de realizar cambios críticos.
    • Referencia: Windows System Restore

  4. Repositorios Oficiales

🤝 Contribuir

Las contribuciones son bienvenidas! Por favor lee CONTRIBUTING.md para más detalles sobre cómo contribuir al proyecto.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

👥 Autores

Gustavo Ernesto Martínez Cárdenas Lead Data Scientist & Architect at DataNicaragua

GitHub LinkedIn

DataNicaragua - Organización

🙏 Agradecimientos

Gracias a todos los contribuidores que hacen posible este proyecto.

📞 Soporte

⭐ Si este proyecto te resulta útil, considera darle una estrella en GitHub!

About

Security-hardened management tool for AI CLI agents. Mitigates supply chain attacks (NPM/Winget) using VSS snapshots, secret backups, and isolated updates.

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v2.0.0 - Security Hardening & Trust Root Migration Latest
Jun 2, 2026

Packages

 
 
 

Contributors

Languages