The project, internally titled Spectrum, represents a prototype for an autonomous “Cyber Reasoning System” (CRS). Unlike traditional security tools that rely on static signatures or hard-coded heuristics, Spectrum utilizes Large Language Models (LLMs)—specifically the DeepSeek-V4 and Qwen families—to perform high-level planning, exploitation, and remediation.
The project is bifurcated into two primary operational modes:
The project is built using a modular Pythonic architecture designed for extensibility and resilience.
main.py: The central entry point. It provides a stylized CLI interface using the rich library, allowing the operator to select between offensive and defensive modules.redteamer.py: Contains the logic for the offensive agent’s “Thought-Action-Observation” loop.blueteamer.py: Houses the “Sentinel” logic for log monitoring and the DeepSeek logic for automated patching.tools.py: The abstraction layer between the AI and the host operating system. It provides the “hands” for the AI, such as terminal execution and HTTP requests.app.py: A Gradio-based web UI that provides a more accessible interface for the agent loops, suitable for demos or remote monitoring.lab.py: This is a deliberately vulnerable Flask application. It serves as the “Sacrifice” or “Target” for the agents. It contains classic vulnerabilities like SQL Injection, Command Injection, and Server-Side Template Injection (SSTI). This serves to test the agent’s skill during development.redteamer.pyThe Red Team agent operates on a continuous feedback loop. It doesn’t just send a payload; it plans, executes, observes the output, and adjusts.
The agent uses a custom token delimiter (䷂) to separate its internal reasoning from its external communication. This allows the AI to “think out loud” about its strategy without cluttering the operator’s log.
# Regex to extract internal thoughts
RE_THINK = re.compile(r'䷂(.*?)䷂', re.DOTALL)
def ai_call(messages, config):
# ... setup client ...
response = client.chat_completion(messages=messages, ...)
msg = response.choices[0].message
# Capture reasoning if the model supports it natively
out = f"䷂\n{msg.reasoning}\n䷂\n" if hasattr(msg, 'reasoning') else ""
return out + (msg.content or "")
The AI interacts with the system by outputting a JSON block at the end of its response. redteamer.py uses robust_extract_tool to find this JSON even if the AI surrounds it with markdown text.
def robust_extract_tool(text):
match = re.search(r'```(?:json)?\s*(.*?)\s*```', text, re.DOTALL)
if not match:
match = re.search(r'(\{[\s\S]*"tool"[\s\S]*\})', text)
if match:
try:
data = json.loads(match.group(1))
return data
except: return None
Once a tool (like execute_terminal or http_request) is identified, it is routed through tools.py, and the result is fed back into the AI’s context as a user message, allowing the AI to learn from the terminal output.
blueteamer.pyThe Blue Team (or “Sentinel”) is arguably the most innovative part of the Spectrum project. It operates as an Autonomous Patching System.
Qwen2.5-3B): A small, fast model that acts as a filter. It watches server.log every 2 seconds. Its job is binary: Is this a hack or a normal request?DeepSeek-V4): If the Sentinel detects an attack, the payload is sent to the more powerful DeepSeek model to verify if the attack actually succeeded and to identify the specific vulnerability type.If an attack is verified, the system calls tools.apply_patch(). This function performs string-based code surgery on the target application (lab.py).
def apply_patch(vulnerability, file_path="lab.py"):
code = full_path.read_text(encoding='utf-8')
# ... logic to find vulnerable patterns ...
if vuln == "sqli":
# Replacing string concatenation with parameterized queries
old_login = 'query = f"SELECT * FROM users WHERE username=\'{username}\' AND password=\'{password}\'"'
new_login = 'query = "SELECT * FROM users WHERE username=? AND password=?"'
code = code.replace(old_login, new_login)
# Update execution call
code = code.replace('cur = db.execute(query)', 'cur = db.execute(query, (username, password))')
# ... write back to file ...
After the patch is applied, the Blue Team agent kills the current server process and restarts it, effectively neutralizing the vulnerability in real-time. ANd then the Sentinel can resume watching the server. Since the Sentinel is only a 3B parameters model, the model can run thousands of times and cost pennies for inference.
tools.pyThe tools.py module is the interface between the LLM’s abstract logic and the concrete operating system. It provides several critical functions:
The execute_terminal function allows the agent to run any shell command. However, it includes a “Self-Preservation” check to prevent the agent from accidentally killing its own process or deleting its own source code.
def execute_terminal(cmd, timeout=30):
my_pid = str(os.getpid())
cmd_tokens = cmd.split()
if "kill" in cmd_tokens and my_pid in cmd_tokens:
return "SYSTEM OVERRIDE: Refusing to kill self."
process = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=timeout)
# ... returns stdout/stderr ...
Since most modern targets are web-based, the http_request tool allows the agent to act as a browser. It uses a persistent requests.Session() to maintain cookies across different cycles, which is vital for exploiting authenticated vulnerabilities like IDOR (Insecure Direct Object Reference).
lab.pyTo demonstrate the system’s power, lab.py provides a rich target environment. It is a Flask app that implements a “SaaS Platform” with several intentional flaws:
/login and /profile routes use f-strings to build queries./ping utility that passes user input directly to the shell./webhook tester that allows the user to provide a URL for the server to fetch, including file:// protocols./announcement feature that uses render_template_string on raw user input./debug endpoint that leaks environment variables and source code.This lab is equipped with a RotatingFileHandler that logs every single request, which serves as the “Sensory Input” for the Blue Team Sentinel.
bake.pyThe project includes a Knowledge Base (KB) system. The bake.py script takes a folder of markdown tutorials or technical documentation and “bakes” them into a SQLite database (kb.sqlite3).
The agent can then use the search_kb tool to query this database. This is a form of RAG (Retrieval-Augmented Generation), allowing the agent to look up specific exploitation techniques or system commands that it might not have in its immediate training data. This file is over 1.7 GB and contains many verified exploits and payloads.
main.py)The CLI uses the rich library to create a CLI-style terminal aesthetic. It features ASCII art, randomized quotes from famous hackers, and a color-coded log of the agent’s progress.
viewer.py)Because LLM outputs can be lengthy, the project includes viewer.py. This uses pywebview to open a local window that renders session.md in real-time. As the agent writes its history to markdown, the viewer automatically scrolls and renders the code blocks and markdown formatting, providing a clean “live stream” of the agent’s brain.
(deprecated)
One of the major challenges of autonomous agents is API instability or quota limits. Spectrum addresses this in redteamer.py via the save_session_state and restore_session functions.
If the agent hits a “402 Payment Required” error or is interrupted by the user, it dumps its entire message history and session cookies into operation_state_recovery.json. When the program is restarted, it detects this file and offers to resume the operation exactly where it left off.
Spectrum is your sword and shield.
Employing a dual-team architecture—comprising both a Red Teamer (offensive) and a Blue Teamer (defensive)—is the superior security strategy because it creates a dynamic, self-improving ecosystem known as “Purple Teaming.”
In this model, the Red Team acts as a necessary catalyst for growth, exposing hidden vulnerabilities and “stress-testing” the environment through creative, real-world exploitation that static scanners often miss. Simultaneously, the Blue Team provides the essential counterbalance, translating those offensive insights into immediate, actionable defenses and automated remediation. Without the Red Team, a defense becomes stagnant and complacent; without the Blue Team, offensive findings are merely academic exercises without a path to resolution.
Together, they form a continuous feedback loop where every successful intrusion leads to a permanent hardening of the system, ensuring that the organization’s security posture evolves as rapidly as the threats it faces.
Warning: This project executes raw shell commands provided by an LLM. It should only be run in a strictly isolated sandbox environment (Docker, VM) with no access to sensitive production data.
The Spectrum project proves that Large Language Models are no longer just “chatbots”—they are capable of complex, multi-step reasoning in technical domains. By combining the offensive creativity of the Red Team agent with the vigilant, automated patching of the Blue Team, Spectrum provides a glimpse into the next generation of cybersecurity: a world where AI agents fight AI agents at machine speed.
The modular design of the tools.py and the dual-model approach in blueteamer.py sets a high bar for how autonomous security systems should be structured: prioritizing fast detection, deep verification, and safe, automated remediation.
While Spectrum’s logic is model-agnostic, its production architecture is specifically optimized for AMD Instinct™ MI300X accelerators. By leveraging AMD ROCm™ 6.0+, we utilize hardware-level optimizations for the DeepSeek-V4 MoE (Mixture-of-Experts) architecture. The massive 192GB of HBM3 memory on the MI300X allows us to keep both our 1.7GB ‘Bake’ Knowledge Base and the full-parameter DeepSeek model in VRAM simultaneously. This eliminates PCIe bottlenecks during RAG (Retrieval-Augmented Generation) operations, enabling the Blue Team Sentinel to achieve the sub-second inference speeds required for real-time autonomous patching.
Walkthrough Metadata: