FastAPI Sidecar — ThreatRecall Docs

Why the sidecar?

Some agent runtimes — especially Python-based — work better over HTTP than directly calling the Node.js API. The sidecar wraps ThreatRecall's recall endpoint and adds:

➜ Natural language routing — pass a plain English query, it resolves it to the right ThreatRecall call
➜ Alias resolution — "Log4Shell" → "CVE-2021-44228" automatically
➜ Relationship traversal — follow actor → CVE → IOC chains in one request
➜ Rate limiting and caching — built in, so your agent doesn't hammer the API

What you'll need

✓ Docker and Docker Compose installed
✓ A ThreatRecall API key
✓ Python 3.9+ if you want to run the client locally

Step-by-step setup

Step 1

Create your docker-compose file

Create a docker-compose.yml in your project directory.

File: docker-compose.yml

version: '3.8'
services:
  threatrecall-sidecar:
    image: ghcr.io/rolandpg/threatrecall-sidecar:latest
    ports:
      - "8000:8000"
    environment:
      THREATRECALL_API_KEY: "your_api_key_here"
      THREATRECALL_BASE_URL: "https://app.threatrecall.ai"
      LOG_LEVEL: "INFO"
    restart: unless-stopped

The sidecar service is defined. It will run ThreatRecall's FastAPI wrapper on port 8000.

Step 2

Start the sidecar

Run the sidecar in the background.

Terminal

docker compose up -d sidecar threatrecall-sidecar
docker compose up -d  # start all services defined in the file

The sidecar starts and listens on http://localhost:8000. Health check at GET /health.

Step 3

Connect your Python agent

Install the client and wire it into your agent.

Terminal

pip install httpx  # or use requests, aiohttp, etc.

File: threatrecall_client.py

import httpx

class ThreatRecallSidecar:
    BASE_URL = "http://localhost:8000"

    def __init__(self, api_key: str):
        self.headers = {"Authorization": f"Bearer {api_key}"}

    def recall(self, query: str) -> dict:
        response = httpx.get(
            f"{self.BASE_URL}/recall",
            params={"q": query},
            headers=self.headers,
            timeout=30.0,
        )
        response.raise_for_status()
        return response.json()

    def resolve_alias(self, alias: str) -> dict:
        response = httpx.post(
            f"{self.BASE_URL}/resolve",
            json={"alias": alias},
            headers=self.headers,
        )
        response.raise_for_status()
        return response.json()

Your agent can now call ThreatRecall through the sidecar over HTTP. The sidecar handles authentication, routing, and caching.

Step 4

Run a natural language query

Query ThreatRecall with plain English. The sidecar resolves aliases and traverses relationships for you.

File: query_example.py

from threatrecall_client import ThreatRecallSidecar

client = ThreatRecallSidecar(api_key="your_api_key_here")

# Natural language query — sidecar handles alias resolution
result = client.recall(
    query="show me all CVEs related to Log4Shell and their associated threat actors"
)

print(result["summary"])
for actor in result["actors"]:
    print(f"- {actor['name']} (confidence: {actor['confidence']})")

The sidecar receives "Log4Shell", resolves it to CVE-2021-44228, queries ThreatRecall's graph, and returns actors who exploit that CVE — all in one call.

Sidecar endpoints

Method	Endpoint	Description
GET	`/health`	Health check — returns `{"status": "ok"}` when running.
GET	`/recall?q=...`	Natural language query. Resolves aliases and traverses the graph automatically.
POST	`/resolve`	Resolve a name or alias to a canonical node ID.
GET	`/graph/:node_id`	Get all edges from a specific node.
POST	`/query`	Structured graph query with filters (node types, relationship types, confidence thresholds).

Troubleshooting

Problem: "Connection refused" when calling localhost:8000
Fix: The sidecar container isn't running. Run docker compose ps to check. If it's stopped, run docker compose up -d. Check logs with docker compose logs threatrecall-sidecar.

Problem: 401 errors from the sidecar
Fix: Your THREATRECALL_API_KEY environment variable in docker-compose.yml is incorrect or missing. Update it with the key from your dashboard.

Problem: Slow responses
Fix: The sidecar caches results for 5 minutes. If you're querying the same thing repeatedly, you should see speed up after the first call. Check docker compose logs for cache hit/miss indicators.