Repository navigation
11 Solucion de Problemas
make install,make run,make serve,make start,make stop,make restart,make verify,make clean,make help. Ejecutamake helppara la lista completa.
Error: Address already in use: 5000 or 8080
Solution 1 - Kill process:
# Find process
lsof -i :5000
lsof -i :8080
# Kill it
kill <PID>Solution 2 - Detener Blackwire:
make stopSolution 3 - Change port:
# Edit backend/main.py
uvicorn.run(app, host="127.0.0.1", port=5001)Error: Python 3.8+ required
Solution - Instalar versión más reciente Python:
Ubuntu/Debian:
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.10 python3.10-venvAlternativa - Use pyenv:
curl https://pyenv.run | bash
pyenv install 3.10.0
pyenv local 3.10.0Problem: HTTPS traffic not decrypting
Solution 1 - Reinstall certificate:
rm -rf ~/.mitmproxy
make installSolution 2 - Verify certificate is installed:
Firefox:
- Preferences → Certificates → View Certificates → Authorities
- Search for "mitmproxy"
Chrome:
certutil -d sql:$HOME/.pki/nssdb -L | grep mitmproxySolution 3 - Check browser proxy config:
- Must be
localhost:8080 - Must check "Use for HTTPS"
Problem: La app nativa no muestra datos or "No se puede conectar"
La app de escritorio (PySide6/Qt) corre en el host y habla con el backend por REST
(http://127.0.0.1:5000) + WebSocket (ws://127.0.0.1:5000/ws). Si la UI aparece vacía
o sin conexión, casi siempre es el backend el que no está arriba.
Check 1 - ¿El backend está corriendo?
curl http://localhost:5000/api/projects
# o arráncalo:
make startCheck 2 - Lanzar la app directamente:
python desktop/run.pyCheck 3 - Smoke test sin UI (headless):
python desktop/run.py --selftestCheck 4 - Verificar PySide6 en el venv:
# PySide6 debe estar instalado en el entorno virtual
python -c "import PySide6; print(PySide6.__version__)"Si el proxy o la app parecen colgados, reinicia el backend:
make restartCheck 1 - Proxy is running:
- Revisa el widget de control del proxy en la barra de estado (verde = running)
Check 2 - Browser proxy config:
# Should be:
HTTP Proxy: localhost:8080
HTTPS Proxy: localhost:8080Check 3 - Certificado instalado:
- See "SSL Certificate Not Working" section
Check 4 - Scope rules:
- Tab "Scope" → Check include/exclude rules
- Temporarily remove all rules to test
Problem: La extensión no se carga en la app de escritorio
Check 1 - Archivo existe:
ls backend/extensions/my_extension.pyCheck 2 - EXTENSION_META correct:
# Debe tener at minimum:
EXTENSION_META = {
"name": "my_extension",
"title": "My Extension",
"description": "...",
"default_config": {"enabled": False}
}Check 3 - register() function:
def register():
return MyExtensionClass()Check 4 - Reiniciar y revisar logs:
La descubierta de extensiones ocurre al arrancar, no en runtime. Reinicia tras cualquier cambio en extensiones y busca errores en la salida:
make restartSymptoms:
- "Base de datos bloqueada" errors
- Requests faltantes
- Caídas del sistema
Solution 1 - Cerrar todas las conexiones:
make stop
# Espera 5 seconds
make startSolution 2 - Verificar integridad de la base de datos:
sqlite3 projects/my-project/blackwire.db "PRAGMA integrity_check;"Solution 3 - Respaldar y recuperar:
# Backup
cp projects/my-project/blackwire.db projects/my-project/blackwire.db.backup
# Recover
sqlite3 projects/my-project/blackwire.db.backup ".dump" | sqlite3 projects/my-project/blackwire.db.new
mv projects/my-project/blackwire.db.new projects/my-project/blackwire.dbError: venv/bin/activate: No such file or directory
Solución:
make installEsto crea el venv, instala requirements.txt y genera el certificado de mitmproxy.
Problem: Launcher in menu doesn't start BlackWire
El lanzador .desktop se distribuye en assets/blackwire.desktop y ejecuta make -C <ruta> run.
make run arranca el backend y lanza la app nativa de escritorio (no abre un navegador).
Al instalarlo, los marcadores INSTALL_PATH deben apuntar a la ruta real de tu copia de Blackwire.
Check 1 - Launcher instalado:
ls ~/.local/share/applications/blackwire.desktopCheck 2 - Path correcto:
cat ~/.local/share/applications/blackwire.desktop | grep -E "Exec|Path"Exec debe ser make -C /ruta/real/a/Blackwire run (sin INSTALL_PATH sin reemplazar).
Solución - Reinstalar el lanzador:
cp assets/blackwire.desktop ~/.local/share/applications/blackwire.desktop
# Reemplaza INSTALL_PATH por la ruta absoluta de tu copia de Blackwire:
sed -i "s|INSTALL_PATH|$(pwd)|g" ~/.local/share/applications/blackwire.desktopNota: El export de proyectos ahora es streaming (serializa el JSON fila por fila), así que ya no consume RAM proporcional al tamaño del historial. Si veías picos de memoria al exportar, ya no aplican.
Cause: Gran cantidad de requests en la base de datos.
Solution 1 - Clean old requests:
DELETE FROM requests WHERE timestamp < date('now', '-30 days');Solution 2 - Crear nuevo project:
- Export important data
- Create fresh project
- Import only needed data
Problem: make stop doesn't work
Solution 1 - API shutdown:
curl -X POST http://localhost:5000/api/shutdownSolution 2 - Find and kill:
ps aux | grep main.py
kill <PID>Nota: Esto detiene el backend. La ventana de la app de escritorio es un proceso aparte: ciérrala normalmente.
Solution 3 - Force kill:
pkill -9 -f "python.*main.py"
pkill -9 -f mitmproxyIf puedes't solve your issue:
- Check logs: Look at terminal output when starting
- Search issues: https://github.com/Glitchboi-sudo/Blackwire/issues
-
Create issue: Proporciona:
- OS and version
- Python version
- Mensaje de error completo
- Pasos para reproducir
- Logs
Blackwire ya crea índices sobre
requests(timestamp, status, scope, saved, type, id) al inicializar la base de datos, así que normalmente no necesitas añadirlos a mano.
Solution 1 - Índices adicionales (si filtras mucho por host):
CREATE INDEX IF NOT EXISTS idx_requests_host ON requests(url);Solution 2 - Enable Modo WAL:
PRAGMA journal_mode=WAL;Verificar: Demasiadas extensiones habilitadas.
Solución: Deshabilitar las extensiones no usadas. Tras el cambio, make restart.