Update README.md

README.md

@@ -4,47 +4,68 @@ language: en
 tags:
 - security
 - autonomous-agent
-- kali-linux
-- llm
-- mcp
+- A self-contained security agent built with Qwen 2.5-7B running locally via LM Studio on Kali Linux. The agent can autonomously execute security tools, analyze results, and take action through an MCP (Model Context Protocol) server. Built for local offensive security automation with real-time tool execution and autonomous decision loops.-linux- llm
 ---
 
 # Autonomous Security Agent
-A self-contained security agent built with Qwen 2.5-7B running locally via LM Studio on Kali Linux. The agent can autonomously execute security tools, analyze results, and take action through an MCP (Model Context Protocol) server.
+
+## System Overview
+
+This agent operates as a fully local autonomous security system that reasons, plans, and executes security tooling through a structured MCP execution layer.
+
+It continuously cycles between:
+- interpreting objectives
+- selecting tools
+- executing system-level security commands
+- analyzing results locally via an embedded LLM
 
 ## Features
 
+A modular autonomous security system built around a local reasoning engine with executable tool orchestration via MCP.
+
 - **Local LLM Backend** — Qwen 2.5-7B served via LM Studio at `192.168.0.39:1234`
 - **Autonomous Tool Execution** — Runs security tools (nmap, masscan) through MCP
 - **Agent Loop** — Continuous reasoning and decision-making
 - **MCP Server** — Tool chain execution with `run_masscan`, `run_nmap`, `write_file`, `read_file`
 
 ## Components
+## System Architecture
 
-- `agent_loop.py` — Main agent reasoning loop
-- `mcp_server.py` — Tool execution server
-- `tools_manifest.json` — Tool definitions
-- `request.json` — Sample request format
+The system is composed of four interacting layers:
 
-## Security Setup
+### 1. Reasoning Layer
+- `agent_loop.py` — Core autonomous decision engine
+- Handles planning, evaluation, and iterative reasoning cycles
 
-### Firewall Configuration
+### 2. Execution Layer
+- `mcp_server.py` — Model Context Protocol execution backend
+- Routes structured tool calls into system commands
 
-- **Outbound**: All traffic allowed
-- **Inbound**: All traffic blocked (default deny)
-- **IDS**: Suricata for behavioral alerting
+### 3. Tooling Layer
+- `tools_manifest.json` — Defines available actions and capabilities
+- `run_nmap`, `run_masscan`, `read_file`, `write_file`
 
-### Network Security
+### 4. Interface Layer
+- `request.json` — Input schema for agent initiation
+- Defines structured prompts and task definitions
 
-- TOR integration for privacy
-- Local-only LLM inference (no external API calls)
-- MCP server bound to localhost only
+## Security Setup
+
+### Firewall Configuration
+- Default policy enforces outbound allow / inbound deny isolation
+- Suricata deployed for behavioral intrusion detection and alerting
+- System operates in execution-restricted network mode during agent runtime
+
+### Network Security Model
+- TOR routing available for privacy-preserving traffic paths
+- All LLM inference remains fully local (no external API dependency)
+- MCP server restricted to localhost-bound execution only
 
 ## Installation & Setup
 
-1. Install Kali Linux with Suricata
-2. Install LM Studio and load Qwen 2.5-7B
-3. Configure firewall rules (see docs/firewall-setup.md)
+1. Prepare a Kali Linux environment with network security tooling (Suricata enabled)
+2. Load Qwen 2.5-7B into LM Studio and expose local endpoint
+3. Configure system firewall rules for isolated execution mode
 4. Clone this repository
 5. Install Python dependencies
 6. Run the agent: `python agent_loop.py`
@@ -58,6 +79,17 @@ See the `docs/` folder for:
 - Suricata configuration
 - MCP server setup
 
+## System Behavior Loop
+
+At runtime, the agent follows a continuous operational cycle:
+
+1. Receive objective via structured input
+2. Interpret intent using local LLM reasoning layer
+3. Select appropriate tool(s) from MCP registry
+4. Execute actions through MCP server
+5. Collect and normalize results
+6. Re-evaluate state and iterate until completion
+
 ## License
 
 MIT