Doc Beacon

Doc Beacon lets security teams embed telemetry beacons into Microsoft Word documents with one command, then receive immediate alerts the moment the file is opened. The service exposes a FastAPI backend for tracker management, a Streamlit control panel for analysts, and a helper script that patches .docx files using the INCLUDEPICTURE field technique (commonly used for marketing pixels) to trigger call-backs without macros.

⚠️ Use responsibly. Always comply with organisational policies and obtain consent before beaconing documents. Many mail clients and viewers disable external content by default; Doc Beacon is designed for internal red-team simulations, leak investigations, and sensitive document watermarking under controlled conditions.

---

Features

• Tracker API – create per-document beacons, list events, and download event history.
• Webhook notifications – receive JSON payloads whenever the document pings the server.
• DOCX instrumentation – insert remote INCLUDEPICTURE fields into Microsoft Word files via scripts/embed_tracker.py.
• SQLite persistence – self-contained storage with schema managed at boot.
• FastAPI docs – navigate to /docs for Swagger UI and /redoc for ReDoc.

---

How it works

1. Create a tracker using POST /api/trackers, optionally registering a webhook URL.
2. Instrument a document by running the helper script. It injects an INCLUDEPICTURE field that references the tracker pixel endpoint.
3. When the DOCX opens in Microsoft Word (or any client that loads remote images), the beacon URL is fetched.
4. Doc Beacon logs the event (IP, user agent, referer) and optionally sends a webhook notification.
5. Investigators query GET /api/trackers/{id}/events to view the history.

LibreOffice and other alternative suites typically do not auto-fetch remote content, or they require users to manually enable it. Expect reliable telemetry primarily on Microsoft Word, Office Online, and viewers that load external images.

---

Quick start

git clone https://github.com/your-handle/doc-beacon.git
cd doc-beacon
python -m venv .venv
.venv\Scripts\activate      # or: source .venv/bin/activate
pip install -e .
doc-beacon                  # starts uvicorn on port 8000

Visit http://localhost:8000/docs to explore the REST endpoints.

---

Streamlit UI

Launch the analyst dashboard in a second terminal once the API is running:

streamlit run streamlit_app.py

The UI walks through tracker creation, DOCX instrumentation (drag-and-drop), and viewing event telemetry. Update the sidebar if your API lives on another host/port.

---

API cheatsheet

Endpoint	Method	Description
/api/trackers	POST	Create a new tracker. Returns tracker metadata and a beacon URL.
/api/trackers/{id}	GET	Fetch tracker details, including the beacon URL.
/api/trackers/{id}/events	GET	Retrieve recorded open events.
/api/pixel/{id}	GET	Tracking pixel endpoint (1×1 PNG). Called automatically by Word.

Example create payload:

{
  "document_name": "Quarterly_Roadmap_v3.docx",
  "description": "Executive-only distribution",
  "webhook_url": "https://hooks.slack.com/services/XXXX/XXXX"
}

Example webhook notification:

{
  "tracker_id": "7c92b63f4f9b4c34bbd602b5d5b467b5",
  "occurred_at": "2025-11-10T01:35:22.439214+00:00",
  "ip_address": "203.0.113.17",
  "user_agent": "Microsoft Office Word/16.0 (Windows NT 10.0; Microsoft Word 16.0.17029; Pro)",
  "referer": null
}

---

Instrumenting a Word document

Once a tracker exists, patch your DOCX:

python scripts/embed_tracker.py .\files\Board-Deck.docx --beacon-url http://localhost:8000/api/pixel/7c92b63f4f9b4c34bbd602b5d5b467b5

The script creates Board-Deck_tracked.docx containing a tiny embedded image that hits the beacon URL whenever Word renders it.

If you need the beacon to be less visible, keep the placeholder text as the default whitespace or convert it to a white-on-white character. For highly sensitive operations, pair Doc Beacon with document protection or watermarking tools.

---

Notifications

Doc Beacon posts JSON payloads to the webhook you supply. Integration ideas:

• Send alerts to Slack/Teams via incoming webhooks.
• Fan out to incident response platforms.
• Enrich with geo-IP data in a background worker.

Webhooks are executed asynchronously to avoid slowing down the pixel response.

---

Testing

Install dev dependencies and run pytest:

pip install -e .[dev]
pytest

---

Security considerations

• User prompts – many clients block external content by default. Educate recipients or pair with controlled environments where remote content is allowed.
• Network egress – ensure the Doc Beacon host is reachable from devices expected to trigger the beacon.
• Logging sensitivity – stored IPs/user agents may be considered personal data; treat logs accordingly.
• Legal/ethical – beaconing external documents can be contentious. Obtain informed consent and follow prevailing laws/regulations.

---

Roadmap

• Optional email notifications.
• S3 or object storage for persistent event logs.
• Automated threat intel enrichment (ASN/geo lookups).
• Hash-based tracker verification for tamper detection.

---

License

MIT © Usman