sec-dashboard - Integracion Auditing_with_PowerShell

Integracion del script Invoke-SecurityAudit.ps1 (repo Auditing_with_PowerShell) como herramienta adicional en sec-dashboard.

Restricción: Solo funciona en Windows (PowerShell 5.1+). El repo debe estar clonado localmente.

---

Estado de la integracion

La integración ya estaba implementada en el código de sec-dashboard. Solo faltaba clonar el repo localmente.

Componente	Estado	Ubicacion
Registro de herramienta	Implementado	backend/config.py:252 (ps_security_audit)
Mapeo handler	Implementado	backend/scanner.py:65
Modulo wrapper	Implementado	backend/tools/audit.py (170 lineas)
Frontend	Automatico	Se renderiza via /api/tools (dinamico)
Repo clonado	Hecho (2026-06-26)	C:\Users\you\Auditing_with_PowerShell
Env var AUDIT_PS_PATH	No necesaria	El wrapper encuentra el script automaticamente

---

Como funciona

Flujo de ejecucion

1. Usuario hace clic en “PS Security Audit” en la categoria System del dashboard
2. Frontend envia POST /api/tools/ps_security_audit/run (no requiere target)
3. scanner.py detecta que es una herramienta de sistema y llama al handler sin target
4. audit.py:ps_security_audit() localiza el script en disco
5. Ejecuta powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File Invoke-SecurityAudit.ps1
6. El script genera carpeta Auditoria_<timestamp>/ con 10 subcarpetas de JSON/CSV/TXT
7. El wrapper lee los JSON, los estructura y devuelve un resumen al dashboard
8. Resultado se muestra en la UI con WebSocket en tiempo real

Deteccion del script (audit.py:_find_script())

El wrapper busca Invoke-SecurityAudit.ps1 en este orden:

1. Env var AUDIT_PS_PATH (puede apuntar al archivo o al directorio del repo)
2. ../Auditing_with_PowerShell/ relativo a sec-dashboard
3. ../../Auditing_with_PowerShell/ (dos niveles arriba)
4. ~/Auditing_with_PowerShell/ ← ruta usada actualmente
5. ~/Desktop/Auditing_with_PowerShell/

No hizo falta setear AUDIT_PS_PATH porque el repo está en C:\Users\you\Auditing_with_PowerShell, que coincide con la ruta 4.

---

Configuracion de la herramienta

Parametro	Valor
ID herramienta	ps_security_audit
Nombre UI	PS Security Audit
Categoria	System
Icono	PS
Timeout	600s (10 min)
Tipo input	none (no requiere target)
Especial	Si (en SPECIAL_TOOLS)

Modulos del audit (10)

El script Invoke-SecurityAudit.ps1 cubre:

1. System info
2. Users
3. Processes
4. Network
5. Logs
6. Files
7. Registry
8. Services
9. LOLBAS
10. Drivers / Hardware

---

Setup (si hay que reinstallar)

1. Clonar el repo

git clone https://github.com/HOSTNAME/Auditing_with_PowerShell.git "$HOME\Auditing_with_PowerShell"

2. Verificar que el wrapper lo encuentra

cd $HOME\sec-dashboard
.venv\Scripts\python.exe -c "from backend.tools.audit import _find_script; print(_find_script())"
# Debe imprimir: C:\Users\you\Auditing_with_PowerShell\Invoke-SecurityAudit.ps1

3. (Opcional) Setear env var si el repo esta en otra ruta

# Temporal (sesion actual)
$env:AUDIT_PS_PATH = "D:\ruta\custom\Auditing_with_PowerShell"
 
# Permanente (usuario)
[Environment]::SetEnvironmentVariable("AUDIT_PS_PATH", "D:\ruta\custom\Auditing_with_PowerShell", "User")

4. Iniciar sec-dashboard y verificar

cd $HOME\sec-dashboard
.venv\Scripts\activate
uvicorn backend.main:app --host 127.0.0.1 --port 8444

Abrir http://127.0.0.1:8444 ←’ categoria System ←’ PS Security Audit debe aparecer.

5. Probar la API directamente

# Arrancar dashboard y luego:
Invoke-WebRequest -Uri "http://127.0.0.1:8444/api/tools" -UseBasicParsing |
  Select-Object -ExpandProperty Content |
  ConvertFrom-Json |
  Where-Object { $_.id -eq "ps_security_audit" }

---

Comandos utiles

# Verificar que el script existe
Test-Path "$HOME\Auditing_with_PowerShell\Invoke-SecurityAudit.ps1"
 
# Ejecutar el script directamente (sin dashboard)
powershell -NoProfile -ExecutionPolicy Bypass -File "$HOME\Auditing_with_PowerShell\Invoke-SecurityAudit.ps1"
 
# Ver ultimas auditorias generadas
Get-ChildItem "$HOME\Auditing_with_PowerShell" -Directory -Filter "Auditoria_*" |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 5 Name,LastWriteTime
 
# Actualizar el repo
cd "$HOME\Auditing_with_PowerShell"
git pull

---

Troubleshooting

”Invoke-SecurityAudit.ps1 not found”

• Verificar que el repo este clonado: Test-Path "$HOME\Auditing_with_PowerShell\Invoke-SecurityAudit.ps1"
• Si está en otra ruta, setear AUDIT_PS_PATH
• El wrapper busca en 5 ubicaciones (ver arriba)

“PowerShell Security Audit only runs on Windows”

• Expected en Linux/macOS. El script es exclusivo de Windows + PowerShell.

El audit tarda mas de 10 minutos

• El timeout del handler es 600s. Si se necesita mas, editar config.py:

  "ps_security_audit": {
      ...
      "timeout": 900,  # 15 min
  }

Audit devuelve resultados vacios

• Ejecutar el script directamente para ver si genera JSON
• Verificar permisos: algunos modulos requieren admin (ejecutar dashboard como admin)
• Revisar stderr_tail en el resultado del dashboard

Execution Policy bloquea el script

• El wrapper usa -ExecutionPolicy Bypass, no deberia pasar
• Si pasa, ejecutar manualmente una vez:

  Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

---

Estructura de archivos relevantes

sec-dashboard/
  backend/
    config.py          # Linea 252: registro de ps_security_audit
    scanner.py         # Linea 65: mapeo a handler
    tools/
      audit.py         # Wrapper completo (170 lineas)

Auditing_with_PowerShell/   (clonado en $HOME)
  Invoke-SecurityAudit.ps1  # Script principal
  README.md
  .gitignore
  LICENSE

---

Notas

• La integración fue disenada por el propio sec-dashboard (ya existía en el código)
• No requiere instalar nada extra en Python (el wrapper usa solo stdlib: asyncio, json, os, platform, pathlib)
• El script de PowerShell es independiente del dashboard: se puede usar por separado
• Resultados del audit se guardan en Auditoria_<timestamp>/ dentro del repo clonado
• Para admins: algunos modulos (logs, registry, services) requieren privilegios elevados
• Ver tambien: Project Overview y Guía de uso