Integración Auditing with PowerShell

sec-dashboard - Integración Auditing_with_PowerShell

Integración 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 integración

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

Componente	Estado	Ubicación
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 líneas)
Frontend	Automático	Se renderiza via /api/tools (dinámico)
Repo clonado	Hecho (2026-06-26)	C:\Users\you\Auditing_with_PowerShell
Env var AUDIT_PS_PATH	No necesaria	El wrapper encuentra el script automáticamente

Cómo funcionafunciona

Flujo de ejecución

1. Usuario hace clic en “PS Security Audit” en la categoría System del dashboard

2. Frontend envía 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

Detección 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.

Configuración de la herramienta

Parámetro	Valor
ID herramienta	ps_security_audit
Nombre UI	PS Security Audit
Categoría	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 está 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 ←’ categoría 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 útiles

# 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 más de 10 minutos

• El timeout del handler es 600s. Si se necesita más, 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 debería 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 también: Project Overview y Guía de uso