Skip to content

🧠 Agent Reasoning Pipeline

Note

👋 Hey there! Siyarix is a personal passion project built by a single developer that is growing and under active development. Some of the architectural components and features described on this page might currently be Planned, Work in Progress, or basic implementations. Stay tuned as it evolves! 🚀

Welcome to the Agent Reasoning Pipeline! This is the "brain" of Siyarix, responsible for taking a user's objective and turning it into real, executed actions.

Think of it as a smart traffic cop: the Planner Router directs requests to either an AI-driven planner (using a Large Language Model or LLM) or a rule-based heuristic planner. This depends on the mode you are running. In autonomous mode, the system follows a dynamic Observe–Reason–Act–Reflect loop. In registry or offline mode, it relies on reliable, deterministic templates.

Note

The dual-planner architecture ensures that Siyarix remains fully functional whether you have an active LLM connection or are operating completely offline.

🏛️ Planner Architecture

Siyarix utilizes a two-planner system, all smoothly coordinated by a unified Planner router:

User Request
    │
    ▼
┌─────────────────────────────────────────┐
│            Planner Router               │
│  (src/siyarix/planner.py)              │
│                                         │
│  mode == "autonomous" ──► AutonomousPlanner │
│  mode == "registry"   ──► RegistryPlanner   │
│  mode == "offline"    ──► RegistryPlanner   │
│  mode == "integrated" ──► try Autonomous →   │
│                            fallback Registry  │
└─────────────────────────────────────────┘

🤖 AutonomousPlanner

(Found in src/siyarix/planner_autonomous.py)

This is our pure, AI-driven planner. It relies entirely on the LLM to figure things out—from verifying if tools are available to installing missing ones and writing the exact shell commands needed.

Key Features: - 🧠 Session-aware Token Optimization: We save on processing costs by sending full tool details only on the first call. Later calls use a much shorter, compact prompt. - 🗣️ Multi-format Response Parsing: Whether the LLM replies in JSON, YAML, Markdown, XML, or just plain text, our system can understand and extract the commands. - 🛠️ Native Tool Calling: When available, we prefer structured tool calls directly from the LLM for better accuracy. - 🛡️ Structured Execution (execute_plan): We provide the LLM with a strict function definition to ensure the plan it generates is properly formatted and safe.

Tip

The AutonomousPlanner works best when the LLM provider supports native structured tool calling (like OpenAI's tool_calls).

⚙️ RegistryPlanner

(Found in src/siyarix/planner_registry.py)

This is our reliable, deterministic planner. It operates entirely without an LLM!

Key Features: - 🔍 Keyword Matching: It uses an inverted keyword index to map plain English words to specific security tools. - 📋 Pre-built Templates: It features over 25 predefined templates (like recon_full, network_scan, linux_privesc) to handle common workflows out of the box. - 🎯 Intent Extraction: A Natural Language Parser picks up on what you want to do (intent) and what you want to target. - 🔄 Smart Fallbacks: If your first-choice tool isn't installed, it automatically rolls over to the next best thing (e.g., swapping nmap for masscan).

🚀 Execution Modes

The AgentCore module (src/siyarix/core/__init__.py) is the main engine, and it supports four different ways of running:

Mode Planner Used Executor Used Needs an LLM?
REGISTRY RegistryPlanner RegistryExecutor No ❌
AUTONOMOUS AutonomousPlanner AutonomousExecutor Yes ✅
HYBRID AutonomousPlanner → RegistryPlanner Both Optional ⚠️
INTERACTIVE RegistryPlanner RegistryExecutor (needs your OK) No ❌

🔄 The Observe–Reason–Act–Reflect Loop

When running in Autonomous Mode, Siyarix works in a continuous, multi-turn loop—just like a human expert would! Here is how the LLMEngineMixin._execute_agent() method handles it:

1️⃣ Observe

First, the agent looks around to understand its environment. It collects: - Environment State: Operating system, available tools, current directory. - Session State: What have we talked about so far? What were the results of the last commands? - Target Context: IPs, domains, or URLs you specified. - Tool Availability: A quick check of the ToolRegistry to see what is installed.

2️⃣ Reason

Next, the LLM puts on its thinking cap. We send it a structured prompt containing the system instructions, conversation history, tool schemas, and your goal.

It then returns a structured plan, looking something like this:

{
    "needs_tools": true,
    "reasoning": "I need to check for open ports to identify running services.",
    "steps": [
        {
            "command": "nmap -sV -p 1-1000 10.0.0.1",
            "description": "Port scan target with service detection"
        }
    ]
}

3️⃣ Act

Now it's time to execute the plan! The commands are run in "waves." Before anything actually runs, it goes through a rigorous safety check: 1. PermissionGate: Checks for syntax errors and dangerous commands. 2. Input Validation: Prevents sneaky stuff like shell injection or path traversal. 3. Shell Review: (Optional) Prompts you to approve, edit, or cancel the command. 4. Execution: Runs the command safely with a timeout and tracks any stray processes. 5. DLP & Secret Redaction: Automatically scrubs API keys, passwords, and sensitive tokens from the output before the LLM sees it.

Warning

Security is our top priority. The agent will never run highly destructive commands without explicit review, and sensitive data is aggressively redacted!

4️⃣ Reflect

Finally, the LLM reviews the output of the commands. Did we get what we needed? - If yes, it sets needs_tools=false and provides a final answer. - If no, it sets needs_tools=true and creates a new plan for the next wave.

Info

The agent can loop up to 12 waves per instruction by default. If it hits that limit, it will stop and ask you for further guidance.

🔧 Tool Call Repair

Sometimes, LLMs get confused and spit out tool calls as plain text instead of structured JSON. No problem! The ToolCallRepair module acts as a safety net to parse and fix these mistakes automatically.

Supported Formats

Syntax Example
Bracket [nmap]{"target": "10.0.0.1", "flags": "-sV"}
XML <function=nmap><parameter=target>10.0.0.1</parameter></function>
Function Call function_call: {"name": "nmap", "args": {...}}

🎯 Fuzzy Name Matching

If the LLM makes a typo (like calling nmaps instead of nmap), our fuzzy matching kicks in. It can tolerate minor spelling mistakes, case differences, and substrings to keep the pipeline moving smoothly.

🛡️ Shell Review

Want to keep a close eye on what the agent is doing? shell_review.py provides an interactive prompt for you to review commands before they run.

╭──────────────── Command Execution Review ─────────────────╮
│ Tool: raw                                                 │
│ Reason: Raw shell command from LLM plan                   │
│                                                           │
│ nmap -sS -sV -O -Pn example.com                           │
╰───────────────────────────────────────────────────────────╯
Review command [edit/run/step/cancel] (run):
  • run: Execute as-is.
  • edit: Tweak the command first.
  • step: Run commands one by one.
  • cancel: Skip it entirely.

Note

In automated environments (like CI/CD pipelines), Shell Review automatically approves commands so it doesn't get stuck waiting for human input.

🛟 Heuristic Fallback (Registry Mode)

When your LLM is down, offline, or just unreachable, the RegistryPlanner steps in to save the day using deterministic logic.

Here is how it thinks: 1. You say: "scan 10.0.0.1" 2. It extracts intent: "scan" 3. It extracts target: "10.0.0.1" 4. It matches a template: network_scan 5. It builds a multi-step plan using tools like nmap, whatweb, and nuclei.

Template Name What it Runs
recon_full nmap → whatweb → gobuster → subfinder → amass → nuclei
web_audit curl → whatweb → nuclei → ffuf → wpscan → nikto
linux_privesc uname → find SUID → find writable → cat cron

⚡ Dependency Resolution & Parallel Execution

Siyarix is smart about how it runs tasks. It organizes steps into Layers.

Layer 1: Recon (Runs immediately)
Layer 2: Scan (Waits for Recon to finish)
Layer 3: Enumerate (Waits for Scan to finish)

Tasks within the same layer (like scanning 5 different ports) run concurrently to save time, making your scans lightning fast! ⚡

📊 Result Synthesis

Once the agent has finished all its waves, it doesn't just dump raw text on you. It synthesizes the data: 1. Deduplicates: Removes repeated findings (based on target, port, and vulnerability). 2. Correlates: Connects the dots between different tools. 3. Scores Severity: Tags issues as Critical, High, Medium, Low, or Info. 4. Summarizes: Gives you a clean, easy-to-read report. 5. Logs to Graph: Saves the findings into a knowledge graph so it remembers them for next time.

🩺 Validation & Recovery

Things fail. Ports are closed, tools crash. The Validator class (src/siyarix/validators.py) is our safety net, offering step-level validation and smart recovery.

If a step fails, the agent can: - RETRY: Try again with a slight change (e.g., adding -Pn to an nmap scan). - RETRY_ALTERNATIVE: Switch tools completely (e.g., if nuclei fails, try nikto). - SKIP: Just move on to the next step. - DEGRADE: Fall back to a simpler execution mode.

Curious about the code? Here is where everything lives:

Module Location What it Does
Planner Router src/siyarix/planner.py The main traffic cop
AutonomousPlanner src/siyarix/planner_autonomous.py The LLM-driven AI planner
RegistryPlanner src/siyarix/planner_registry.py The offline, rule-based planner
AgentCore src/siyarix/core/__init__.py Central orchestrator
LLMEngineMixin src/siyarix/chat/engine.py Agent loop with multi-wave planning
ToolCallRepair src/siyarix/tool_call_repair.py Fixes broken LLM tool calls
ShellReview src/siyarix/shell_review.py Interactive command approval
Validator src/siyarix/validators.py Error handling and recovery
ToolRegistry src/siyarix/registry.py Tool discovery and capability indexing
ToolCapabilityGraph src/siyarix/tool_graph.py Tool chaining and similarity graph
ToolAvailability src/siyarix/tool_availability.py Pre-execution availability evaluation
DangerAnalyzer src/siyarix/security_hardening.py Keeps dangerous commands in check
CompactionEngine src/siyarix/compaction.py Context window compaction for long histories