foxglove: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Foxglove is an AI-powered adversary engagement tool that generates high-fidelity, context-aware honeyfiles using Anthropic's Claude, and optionally mints and embeds honeytokens from a Thinkst Canary console. It automates creation of convincing fake data for defensive security operations, aligned with the MITRE Engage framework.

Glossary

• honeyfile — a decoy document produced by foxglove generate (PDF, DOCX, XLSX, etc.).
• honeytoken — a callback URL/hostname minted on a Thinkst Canary console via foxglove thinkst create. Honeytokens can be passed to foxglove generate --honeytokens so the LLM weaves them into honeyfile content.

Workflow (two moments):

1. Optional — mint honeytokens via foxglove thinkst create and note their callback URLs/hostnames.
2. Generate honeyfiles via foxglove generate ... [--honeytokens <urls>]. CLI validation → context ingestion → campaign planning (structured JSON via Pydantic) → content generation per honeyfile → file assembly to disk.

Supported honeyfile formats: PDF, Encrypted PDF (EPDF), DOCX, XLSX, PPTX, MD, CONF, JSON, XML.

Development Commands

# Install/sync dependencies
uv sync

# Generate honeyfiles
uv run python -m foxglove generate \
  --base-dir /tmp \
  --operation op_alpha \
  --num-files 10 \
  --formats pdf,docx,xlsx \
  --teams it,infra \
  --company "description of target company" \
  --file-content "description of expected file content" \
  [--honeytokens https://x.canary.tools/...,host.y.canarytokens.com]

# Manage honeytokens on a Thinkst Canary console
uv run python -m foxglove thinkst create \
  --domain-hash <your-domain-hash> --kind dns --flock flock:default --memo "..."
uv run python -m foxglove thinkst list --domain-hash <your-domain-hash>
uv run python -m foxglove thinkst remove --domain-hash <your-domain-hash> <canarytoken-id>

# Run tests
uv run pytest

# Run a single test file
uv run pytest tests/test_generator.py

# Run a single test by name
uv run pytest -k "test_name"