How octopus237/agentic-ai works
Purpose and Entry Point
This is a local, LLM-driven Wazuh security investigation service. An analyst submits a natural-language question; an Ollama-hosted model selects Wazuh data tools, iterates on evidence, and returns a verdict with an auditable tool-call trail.
The executable entry point is app.py, which provides Flask UI/API hosting and lifecycle commands (start, stop, status, restart, run).
Paths: app.py, README.md
Application and Process Host
app.py owns the Flask web interface, request handling, live investigation control, cancellation, report presentation, auto-run scheduling, and background process management. It binds according to UI_HOST and UI_PORT, and its managed background mode writes PID/log artifacts.
This is the orchestration boundary between browser-facing interaction and the agent runtime.
Paths: app.py
Agentic Investigation Runtime
agent_tools.py implements the investigation loop. It sends the analyst prompt and tool definitions to Ollama, receives model-selected tool calls, executes them, feeds observations back into the conversation, and repeats until the model produces a final answer or reaches AGENTIC_MAX_STEPS.
The model is responsible for investigative planning and convergence; the application enforces the tool-call budget and can stop an active run.
Paths: agent_tools.py
Tool Boundary and Audit Trail
The agent exposes constrained investigation tools rather than direct model access to Wazuh. Tool results become subsequent model context, while each invoked query/call is recorded as an audit trail. Completed runs persist a verdict plus this trail; history is JSON-backed and capped at 50 reports.
This boundary is important for traceability: the LLM plans, but repository code performs external data access.
Paths: agent_tools.py, app.py
Wazuh Data Access Layer
client.py isolates external Wazuh communication from agent reasoning. It accesses two distinct services:
• Wazuh Indexer API on port 9200, using basic authentication, for alerts, aggregations, and event timelines.
• Wazuh Server API on port 55000, using token authentication, for live host inventory.
The design assumes one reachable Wazuh manager and one indexer. Credentials, endpoint URLs, and TLS behavior come from environment configuration.
Paths: client.py, agent_tools.py
Primary Control and Data Flow
1. Browser submits a question or scheduled triage begins in app.py.
2. app.py starts an agent run and streams progress, reasoning/tool activity, and final output to the UI.
3. agent_tools.py calls the configured Ollama model and processes requested tools.
4. Tool implementations call client.py.
5. client.py queries Wazuh Indexer and/or Server APIs and returns normalized results to the agent loop.
6. The final verdict and full audit trail are saved and made available in the Reports UI.
Paths: app.py, agent_tools.py, client.py
Runtime Dependencies and Infrastructure
The service requires Python 3.10+, Flask/CORS for the local UI, requests for Wazuh HTTP access, and the Ollama Python client. Ollama may be local or network-hosted and must provide a capable tool-calling model. Wazuh manager, indexer, and Ollama are external network dependencies configured through .env.
Paths: app.py, agent_tools.py, client.py
Main entry points: agent_tools.py Investigation Loop · app.py Flask Host & Orchestrator · client.py Wazuh Client
Components 11
Local Investigation Service
- Flask Host & Orchestrator · Hosts UI/API, controls runs, streaming, scheduling, and managed process lifecycle.
app.py - Auto-run Scheduler
app.py - Investigation Loop · Enforces step budget and cancellation while iterating model tool calls.
agent_tools.py - Constrained Tools · Executes repository-controlled Wazuh queries and records calls.
agent_tools.py - Reports & Audit History · Stores verdicts and tool-call trails; capped at 50 reports.
app.py - Wazuh Client · Normalizes authenticated responses from Wazuh services.
client.py
External Services
- Ollama Model · Selects tools and produces the final investigative answer.
- Wazuh Indexer API · Provides alerts, aggregations, and event timelines.
- Wazuh Server API · Provides live host inventory through token authentication.
Other components
- Analyst Browser · Submits questions and views live investigation results.
- Environment Configuration · Supplies endpoints, credentials, TLS settings, host, and port.
Connections 16
- Analyst Browser → Flask Host & Orchestrator: questions / UI requests
- Flask Host & Orchestrator → Analyst Browser: progress and reports
- Auto-run Scheduler → Flask Host & Orchestrator: starts triage
- Flask Host & Orchestrator → Investigation Loop: starts / cancels run
- Investigation Loop → Ollama Model: prompt and tool definitions
- Ollama Model → Investigation Loop: tool calls / final answer
- Investigation Loop → Constrained Tools: executes requested tools
- Constrained Tools → Wazuh Client: query operations
- Wazuh Client → Wazuh Indexer API: basic-auth queries
- Wazuh Client → Wazuh Server API: token-auth inventory
- Constrained Tools → Investigation Loop: observations and audit calls
- Investigation Loop → Reports & Audit History: verdict and tool trail
- Flask Host & Orchestrator → Reports & Audit History: presents saved reports
- Environment Configuration → Flask Host & Orchestrator: UI host / port
- Environment Configuration → Investigation Loop: model settings
- Environment Configuration → Wazuh Client: endpoints and credentials