Contributing

Contributions are welcome — whether you're a security researcher, AI engineer, or someone who cares about making defense better through offense.

---

Development Setup

Prerequisites: Docker, Docker Compose v2, and uv (for Python tooling locally).

git clone https://github.com/PurpleAILAB/Decepticon.git
cd Decepticon

# Copy and configure environment
cp .env.example .env
# Edit .env — set at least one provider key, or set OLLAMA_API_BASE + OLLAMA_MODEL for local Ollama

# Start services with hot-reload (daily dev loop)
make dev

# Or run the full OSS UX (launcher → onboard → CLI) on local code
make dogfood

make dev uses docker compose watch — source changes sync into containers automatically without rebuilding. make dogfood is the release-shape verification path; see makefile-reference.md for the full target list.

---

Project Structure

decepticon/          # Core Python package (LangGraph agents, middleware, tools)
├── agents/          # Agent factory functions (create_*_agent)
├── core/            # Config, engagement document schemas, logging, streaming helpers
├── llm/             # Model profiles, LiteLLM configuration
├── middleware/       # Skills, filesystem, OPPLAN, safe command, fallback, etc.
└── tools/           # Bash, research (KG, CVE, chain planning), reporting

skills/              # Skill library (SKILL.md files organized by kill chain phase)

clients/
├── cli/             # TypeScript/Ink terminal UI
├── web/             # Next.js 16 web dashboard
└── shared/          # Shared streaming utilities (@decepticon/streaming)

config/              # LiteLLM proxy config (litellm.yaml)
containers/          # Dockerfile per service

---

Quality Gates

Before opening a PR, run the quality checks:

make quality         # Full gate: Python + CLI + Web (run before opening a PR)

make lint            # Python only: ruff check + ruff format --check + basedpyright
make lint-fix        # Auto-fix Python lint and formatting
make quality-cli     # CLI: typecheck + build + vitest
make web-lint        # Web dashboard ESLint

make test            # Python tests in Docker
make test-local      # Python tests locally (requires uv sync --dev)

Minimum Python version: 3.13

---

Adding an Agent

1. Create the agent module. Pick a bundle:
   • decepticon/agents/standard/{name}.py for OSS-blessed agents shipped by default
   • decepticon/agents/plugins/{name}.py to demonstrate the community-plugin shape The file exposes a create_{name}_agent() factory.
2. Follow the middleware stack pattern from an existing agent (e.g., standard/recon.py)
3. Define the agent's skill sources in the SkillsMiddleware configuration
4. Subagents only: add a module-level SUBAGENT_SPEC = SubAgentSpec(...) declaring parent_agents=(...), bundle=..., and priority=.... Register it under [project.entry-points."decepticon.subagents"] in pyproject.toml. The relevant main agent picks it up automatically via load_subagents_for_parent(...). See decepticon/plugin_loader.py for the contract.
5. Create a skills directory at skills/{bundle}/{name}/ mirroring the agent bundle (standard/ or plugins/).

Activating plugin bundles

Decepticon defaults to the lean standard bundle. To activate additional bundles (e.g. the plugins bundle that ships vulnresearch), use the 4-tier hierarchy (highest precedence wins):

1. DECEPTICON_PLUGINS env var — runtime override:

   DECEPTICON_PLUGINS=standard,plugins langgraph dev   # or "*" for all
   

2. .decepticon.toml in CWD — per-checkout opt-in:

   [plugins]
   enabled = ["standard", "plugins"]
   

3. pyproject.toml in CWD — project-default opt-in:

   [tool.decepticon.plugins]
   enabled = ["standard", "plugins"]
   

4. Hardcoded default — ["standard"].

The OSS repo itself ships with both bundles enabled via the project-level pyproject.toml (so make dev / make benchmark work out of the box). End-user installs that just pip install decepticon get the lean standard-only default (neo4j and other heavy features are opt-in extras, e.g. decepticon[neo4j]). Downstream Docker images override via ENV DECEPTICON_PLUGINS=standard,vendor to activate their own bundle.

The OSS-shipped langgraph.json matches the lean default — it only lists the 10 standard graphs. To expose plugin graphs to LangGraph Platform, emit the manifest dynamically:

LANGSERVE_GRAPHS="$(python -m decepticon.graph_registry)" langgraph dev

That CLI emits the merged manifest of every active bundle plus any external decepticon.agents entry-points.

---

Adding a Skill

1. Create a directory: skills/{category}/{skill-name}/
2. Write SKILL.md following the skill format
3. Add references/ for content over 100 lines
4. Add scripts/ for automation the agent should execute
5. Restart — SkillsMiddleware discovers skills at agent boot

No registration required. Skills are discovered automatically from the agent's configured source paths.

---

Testing

Python tests live in decepticon/tests/. Run inside Docker for a clean environment:

make test            # pytest in container
make test-local      # pytest locally (requires: uv sync --dev)

CLI tests run via make quality-cli (typecheck + build + vitest), or directly:

npm run test --workspace=@decepticon/cli

When adding a new agent or tool, add corresponding tests in decepticon/tests/.

---

Pull Request Process

1. Fork the repository
2. Create a feature branch from main: git checkout -b feat/your-feature
3. Make changes — keep commits focused and descriptive
4. Run make quality and ensure all checks pass
5. Open a Pull Request against main
6. In the PR description, include:
   • What changed and why
   • How to test the change
   • Any relevant MITRE ATT&CK technique IDs (for new agent capabilities or skills)

---

Areas Where Help Is Welcome

Area	What's needed
New skills	More OSINT, cloud attack, and post-exploitation skill coverage
C2 profiles	Havoc framework support (c2-havoc profile)
Web dashboard	UX improvements, new views, mobile responsiveness
Documentation	Tutorials, walkthroughs, translated READMEs
Bug reports	Open an issue with reproduction steps

---

Community

Join the Discord to ask questions, share engagement logs, discuss techniques, or connect with others working on the project.