Skip to content

AI Agents Documentation

This folder defines the LLM-first agent architecture for the EASM Platform.

Agents are LLM-powered analytical modules operating on the attack surface graph and vulnerability dataset. They receive structured context from the platform, transform that context into an agent-specific prompt, call an interchangeable LLM provider, validate the model output, and store a structured AgentResponse.

Backend agent execution is not implemented yet. The current product has an admin-only AI Agents frontend settings page where administrators can separate agents into Advisory and Operational categories, select enabled agents, choose run modes, and configure provider, model, and API key values. The database schema already includes agent_runs, which is the intended audit/storage table for future agent executions.

Contents

  • Agent Catalog - Advisory and Operational agent types
  • Schemas - AgentContext, prompt input data, AgentResponse, actions, and storage
  • Implementation Plan - LLM-first backend architecture, providers, prompt lifecycle, and execution flow
  • Safety and Governance - scope restrictions, provider safety, approval rules, and auditability
  • Roadmap - phased implementation path for LLM-backed agents

High-Level Model

The agent model is:

EASM platform data
  |
  v
AgentContext
  |
  v
Prompt Builder
  |
  v
LLM Provider
  |
  v
Structured AgentResponse
  |
  v
validation + agent_runs audit record

Agents reason about:

  • attack paths
  • risk prioritization
  • false positives
  • exposure analysis
  • recommended next actions
  • executive reporting

Agents should never be treated as trusted autonomous operators. They are reasoning and decision-support modules that must stay inside approved scope and produce auditable, machine-readable output.

Agent Categories

Advisory Agents

Advisory agents analyze existing findings and generate recommendations, summaries, risk context, and attack path explanations.

Current advisory agents:

  • Risk Agent
  • Attack Path Agent
  • Executive Summary Agent

Safe default:

  • no scan execution
  • no scope mutation
  • no vulnerability mutation
  • recommendation-only output

Operational Agents

Operational agents analyze findings and propose follow-up investigation. They may recommend scans, deeper profiles, or additional validation steps, but they do not execute actions automatically.

Current operational agents:

  • Recon Agent
  • Pentest Agent

Safe default:

  • suggestion-only output
  • scan-related actions require approval
  • all targets must remain inside approved scope
  • no exploitation, brute-force, or scope expansion

Current Implementation State

Implemented today:

  • Frontend route: /ai-agents
  • Admin-only UI access through the main layout
  • Local frontend settings:
  • enabled agent IDs
  • per-agent run modes
  • provider
  • model
  • API key
  • Supported UI providers:
  • local model runtime
  • OpenAI
  • Claude
  • Database table:
  • agent_runs

Not implemented yet:

  • backend/internal/agents package
  • Agent execution service
  • Prompt builder
  • LLM provider adapters
  • Worker integration after scan completion
  • Agent API endpoints
  • Persisted backend agent settings
  • Applying or approving AgentResponse actions

Target Principles

  • Agents are AI-native reasoning modules built around prompt templates and structured model output.
  • Prompt templates are first-class architecture components.
  • Providers are interchangeable and agents must not depend on one vendor.
  • All model outputs must be structured, validated, and auditable.
  • Agents must only operate within approved organization scope.
  • Operational suggestions require explicit policy or human approval.
  • Frontend settings are not a security boundary.