The Problem

Red‑team teams spend large amounts of manual effort orchestrating toolchains, logging output, and stitching together attack phases. Without automation, repeatable, auditable engagements are hard to scale, and knowledge transfer between operators is limited.

What This Does

Decepticon implements an autonomous multi‑agent red‑team framework. The CLI entry point frontend/cli/cli.py loads prompt definitions (src/prompts/prompt_loader.py), constructs LLM‑backed agents (src/agents/swarm/*.py), and drives a workflow through the swarm graph (src/graphs/swarm.py). The web UI (frontend/web/pages/01_Chat.py and related components) offers an interactive front‑end that re‑uses the same executor logic (frontend/web/core/executor.py). Core utilities such as LLM configuration (src/utils/llm/config_manager.py), memory handling (src/utils/memory.py), and logging (src/utils/logging/logger.py) are shared across both interfaces.

How It Is Wired

Execution starts in frontend/cli/cli.py (the declared entry point).

  1. CLI bootstrap – parses arguments and calls frontend/web/core/executor_manager.run() which in turn creates an Executor (src/utils/executor.py).
  2. Prompt loading – Executor imports src/prompts/prompt_loader.py; this module imports 11 other prompt files (e.g., src/prompts/base/initaccess.py) and is the most‑connected source (Ca = 4, Ce = 11, instability 0.73).
  3. Agent creation – src/agents/swarm/__init__.py pulls the prompt objects into agent classes (InitAccess, Planner, Recon, Summary). Each agent references the LLM config via src/utils/llm/config_manager.py (Ca = 7, Ce = 1, low instability).
  4. Graph orchestration – src/graphs/swarm.py builds a directed workflow linking the agents; it imports the agents and the shared memory store (src/utils/memory.py). The graph module is also a hub (Ca = 4, Ce = 6).
  5. Execution – Executor.run() iterates the graph, calling each agent’s run() method, which ultimately invokes the LLM through src/utils/llm/models.py. Results are logged by src/utils/logging/logger.py (high nesting depth, see health findings).
  6. Web UI path – The same executor logic is exposed via frontend/web/core/executor.py, which is invoked by the Streamlit app (frontend/streamlit_app.py) and the Flask‑based UI (frontend/web/pages/01_Chat.py). Both routes converge on the same core modules, giving a single blast radius for changes to Executor, prompt_loader, or the LLM config manager.

No circular imports were detected, so the dependency graph is acyclic. The largest fan‑in modules are src/prompts/prompt_loader.py and frontend/web/utils/constants.py, meaning changes there affect many downstream files.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/Decepticon
cd Decepticon

# Install Python deps (pip is the declared manager)
pip install -r requirements.txt   # or: pip install .   (pyproject.toml)

# Build and run the attacker container (Dockerfile.attacker)
docker compose -f docker-compose.yml up --build   # pulls kalilinux/kali-rolling

# Run the CLI locally (alternatively, exec into the container)
python frontend/cli/cli.py   # shows available commands in the help output

Configuration: copy .env.example to .env and populate any required keys (e.g., OpenAI API tokens) – the repo does not ship defaults, so the application will abort until they are set.

Web UI: after the container is up, open http://localhost:8501 (Streamlit) or http://localhost:5000 (Flask) to access the chat‑based interface.

Real‑World Use

A penetration‑testing consultancy could embed Decepticon in their CI pipeline to automatically generate reconnaissance reports. A simple script could invoke frontend/cli/cli.py --target 10.0.0.5 --plan full, capture the JSON replay (frontend/web/core/chat_replay.py), and archive it alongside manual findings for client delivery.

Code Health & Issues

  • HIGH – No test suite – 82 source files, zero test files.
  • HIGH – No CI workflow – repository lacks any GitHub Actions or other pipeline definitions.
  • HIGH – Privileged Docker & host networking – docker-compose.yml sets privileged: true and network_mode: host.
  • HIGH – No build gate for deployable artifacts – images are built but never validated in CI.
  • MEDIUM – No Dependabot/Renovate – only pyproject.toml and requirements.txt are present.
  • MEDIUM – Mutable base image – Dockerfile.attacker uses kalilinux/kali-rolling tag.
  • MEDIUM – Large binaries in repo – .github/web.gif (40 MB) and other GIFs exceed 5 MB.
  • MEDIUM – No non‑root user in Dockerfile – containers run as root by default.
  • MEDIUM – Deep nesting & duplicated code – files such as src/utils/logging/logger.py have indentation depth 8; repeated 6‑line blocks appear in >25 files.
  • MEDIUM – Broad exception handling – many except: clauses swallow errors.
  • MEDIUM – Oversized CLI file – frontend/cli/cli.py contains 928 lines, making local changes high‑risk.

The Bottom Line

Decepticon provides a concrete, code‑driven red‑team automation layer with a clear separation between CLI, web UI, and shared agent logic. Its architecture is functional but suffers from serious production‑readiness gaps: no tests, no CI, and unsafe Docker defaults. Teams that need rapid prototyping of AI‑assisted attacks can adopt it, but must first harden the build pipeline, add test coverage, and remediate the highlighted security and maintainability issues.