Skip to content

10 API Reference

Jump to bottom
glitchboi edited this page Oct 30, 2026 · 3 revisions

API Reference

El backend de Blackwire es una aplicación FastAPI. La lógica REST está organizada por dominio: hay un router (APIRouter) por feature en backend/routes/, y main.py los registra a todos.

Esta API la consume la app de escritorio nativa (PySide6/Qt) sobre REST (http://127.0.0.1:5000) + WebSocket (ws://127.0.0.1:5000/ws), y también el servidor MCP (blackwire-mcp) que la expone a agentes de IA. Ya no existe un frontend web.

La forma más fiable de explorar la API completa es la documentación interactiva Swagger, disponible mientras el backend corre:

http://localhost:5000/docs

Esta página documenta las rutas más usadas, agrupadas por router. Los nombres y prefijos coinciden con el código fuente en backend/routes/.

Organización por routers

Router (backend/routes/) Prefijo de rutas Dominio
projects.py /api/projects Gestión de proyectos (CRUD, selección)
export_import.py /api/projects/{name}/export…, /api/projects/import Export/Import Blackwire y Burp
proxy.py /api/proxy, /api/shutdown, /api/browser Control del proxy y del servidor
intercept.py /api/intercept, /api/intercept_response Interceptación de requests/responses
requests.py / search.py /api/requests, /api/v2/requests, /api/filter-presets Historial HTTP, búsqueda HTTPQL, presets
scope.py /api/scope Reglas de scope
repeater.py /api/repeater Repeater
collections.py /api/collections Colecciones y ejecución por pasos
intruder.py /api/intruder Ataques de Intruder
session.py /api/session Macros y session rules
chepy.py /api/chepy Operaciones del Cipher (Chepy)
websocket.py /api/websocket Conexiones y frames WebSocket
git.py /api/git Snapshots Git del proyecto
extensions.py /api/extensions Sistema de extensiones
webhook.py /api/webhooksite Integración con webhook.site
bypass.py /api/bypass Reglas de bypass de scope
rendering.py /api/requests/{id}/render… Render/replay de respuestas
internal.py /api/internal Endpoints internos (los llama el addon mitmproxy)

Proyectos (projects.py)

GET /api/projects

Listar todos los proyectos.

Response:

{
  "projects": [
    {
      "name": "my-project",
      "description": "Test project",
      "created_at": "2024-01-01T00:00:00"
    }
  ]
}

POST /api/projects

Crear nuevo proyecto.

Request:

{
  "name": "my-project",
  "description": "Test project"
}

GET /api/projects/current

Obtener el proyecto activo.

POST /api/projects/{name}/select

Cambiar el proyecto activo.

PUT /api/projects/{name}

Actualizar metadatos del proyecto.

DELETE /api/projects/{name}

Eliminar proyecto (borra su carpeta y base de datos).

Cada proyecto vive en projects/{name}/ con su config.json y su base de datos SQLite blackwire.db.

Export / Import (export_import.py)

GET /api/projects/{name}/export

Exportar el proyecto en formato Blackwire (JSON). La respuesta es streaming: el JSON se serializa fila por fila, por lo que la memoria se mantiene plana sin importar el tamaño del historial.

GET /api/projects/{name}/export-burp

Exportar como Burp Suite XML.

POST /api/projects/{name}/import

Importar datos en formato Blackwire dentro de un proyecto existente.

POST /api/projects/{name}/import-burp

Importar desde Burp Suite XML.

POST /api/projects/import

Crear un proyecto nuevo a partir de un archivo de export Blackwire.

Proxy y servidor (proxy.py)

GET /api/proxy/status

Obtener el estado del proxy.

Response:

{
  "running": true,
  "port": 8080,
  "mode": "regular"
}

POST /api/proxy/start

Iniciar el proxy.

Parámetros (query):

  • port - Puerto de escucha (default: 8080)
  • mode - regular, upstream, socks5, reverse, transparent
  • extra - Flags adicionales para mitmproxy (los flags peligrosos se filtran)

POST /api/proxy/stop

Detener el proxy.

POST /api/browser/launch

Lanzar un navegador preconfigurado contra el proxy.

POST /api/shutdown

Apagar el backend.

Interceptación (intercept.py)

GET /api/intercept/status

Estado de la interceptación.

POST /api/intercept/toggle

Activar/desactivar la interceptación de requests.

GET /api/intercept/pending

Listar requests pausados a la espera de decisión.

POST /api/intercept/{request_id}/forward

Reenviar (con posibles modificaciones) un request pausado.

POST /api/intercept/{request_id}/drop

Descartar un request pausado.

POST /api/intercept/forward-all

Reenviar todos los requests pendientes.

POST /api/intercept/drop-all

Descartar todos los requests pendientes.

POST /api/intercept/toggle_responses

Activar/desactivar la interceptación de responses.

GET /api/intercept/pending_responses

Listar responses pausadas.

POST /api/intercept_response/{response_id}/forward

Reenviar una response pausada.

POST /api/intercept_response/{response_id}/drop

Descartar una response pausada.

También existen /api/intercept_response/forward-all y /drop-all.

Historial y búsqueda (requests.py, search.py)

No existe /api/history. El historial vive en /api/requests y la búsqueda HTTPQL en POST /api/requests/search.

GET /api/requests

Obtener el historial HTTP.

Parámetros (query):

  • limit - Máximo de resultados (default: 10000)
  • saved_only - Solo requests marcados como guardados
  • in_scope_only - Solo requests dentro de scope
  • search - Filtro simple por substring de URL

Response: lista de items resumidos del historial.

GET /api/requests/{rid}/detail

Detalle completo de un request (headers, body, response).

POST /api/requests/search

Búsqueda con HTTPQL. La app de escritorio envía el AST de la query ya parseado.

Request:

{
  "ast": { "...": "AST de HTTPQL" },
  "saved_only": false,
  "in_scope_only": false,
  "page": 1,
  "page_size": 500
}

Response:

{
  "requests": [ "..." ],
  "total": 1234,
  "page": 1,
  "page_size": 500,
  "total_pages": 3
}

PUT /api/requests/{rid}/save

Marcar/desmarcar un request como guardado.

DELETE /api/requests/{rid}

Eliminar un request.

DELETE /api/requests

Vaciar el historial.

Detalle extendido (v2)

  • GET /api/v2/requests/{rid}/detail
  • GET /api/v2/requests/{rid}/body
  • GET /api/v2/requests/{rid}/response-body
  • GET /api/v2/requests/{rid}/sizes

Filter Presets

  • GET /api/filter-presets
  • POST /api/filter-presets
  • DELETE /api/filter-presets/{preset_id}

Scope (scope.py)

GET /api/scope

Obtener configuración y reglas de scope.

POST /api/scope/rules

Crear una regla de scope.

PUT /api/scope/rules/{rule_id}

Actualizar una regla.

DELETE /api/scope/rules/{rule_id}

Eliminar una regla.

Repeater (repeater.py)

GET /api/repeater

Obtener todos los requests guardados del repeater (incluye su history, el timeline de respuestas, que persiste entre reinicios).

POST /api/repeater

Guardar un request del repeater.

PUT /api/repeater/{item_id}

Actualizar un request guardado (nombre, datos del request, timeline).

DELETE /api/repeater/{item_id}

Eliminar un request del repeater.

POST /api/repeater/send-raw

Enviar un request en crudo y obtener la response (con manejo opcional de redirects).

Colecciones (collections.py)

GET /api/collections

Listar colecciones.

POST /api/collections

Crear colección.

PUT /api/collections/{cid}

Actualizar colección.

DELETE /api/collections/{cid}

Eliminar colección.

GET /api/collections/{cid}/items

Obtener los pasos de una colección.

POST /api/collections/{cid}/items

Agregar un paso.

PUT /api/collections/{cid}/items/{iid}

Actualizar un paso.

DELETE /api/collections/{cid}/items/{iid}

Eliminar un paso.

POST /api/collections/{cid}/items/{iid}/execute

Ejecutar un paso, extrayendo variables (JSONPath) de la response.

Intruder (intruder.py)

  • GET /api/intruder/attacks - Listar ataques guardados.
  • POST /api/intruder/attacks - Crear un ataque.
  • GET /api/intruder/attacks/{aid} - Detalle de un ataque.
  • PUT /api/intruder/attacks/{aid} - Actualizar.
  • DELETE /api/intruder/attacks/{aid} - Eliminar.

Sesión: Macros y Rules (session.py)

Macros:

  • GET /api/session/macros
  • POST /api/session/macros
  • PUT /api/session/macros/{macro_id}
  • DELETE /api/session/macros/{macro_id}
  • POST /api/session/macros/{macro_id}/execute

Session Rules:

  • GET /api/session/rules
  • POST /api/session/rules
  • PUT /api/session/rules/{rule_id}
  • DELETE /api/session/rules/{rule_id}

Cipher / Chepy (chepy.py)

GET /api/chepy/operations

Listar las operaciones disponibles del encoder/decoder.

POST /api/chepy/bake

Ejecutar una receta (lista encadenable de operaciones) sobre un input.

WebSocket (websocket.py)

GET /api/websocket/connections

Listar las conexiones WebSocket capturadas.

GET /api/websocket/frames

Listar frames (filtrables por conexión).

POST /api/websocket/resend

Reenviar un frame (posiblemente editado).

Git (git.py)

POST /api/git/commit

Crear un snapshot Git del estado del proyecto.

GET /api/git/history

Listar el historial de commits.

Extensiones (extensions.py)

GET /api/extensions

Obtener la metadata de todas las extensiones.

PUT /api/extensions/{name}

Actualizar la configuración de una extensión.

El endpoint legacy GET /api/extensions/{name}/ui.js (UI dinámica .ui.jsx compilada) fue retirado en v2.0.0 junto con el frontend web. Las extensiones ahora son solo Schema-Driven: la app de escritorio renderiza su formulario desde EXTENSION_META["ui_schema"].

webhook.site (webhook.py)

  • POST /api/webhooksite/apikey - Configurar API key.
  • POST /api/webhooksite/token - Crear/registrar token.
  • POST /api/webhooksite/refresh - Refrescar requests recibidos.
  • GET /api/webhooksite/requests - Listar requests capturados.
  • DELETE /api/webhooksite/requests - Limpiar requests.

Endpoints internos (internal.py)

Uso interno. Los invoca el addon de mitmproxy (mitm_addon.py), no la app de escritorio.

  • POST /api/internal/request - El addon registra un request/response capturado.
  • POST /api/internal/intercept - El addon consulta/aplica decisiones de interceptación.

Clone this wiki locally