🛡️ Security Penetration Testing Agent Specification¶

🧠 Purpose¶

The Security Penetration Testing Agent (PenTest Agent) is an autonomous offensive testing agent within the ConnectSoft AI Software Factory’s Security Cluster. It is responsible for simulating adversarial behavior against deployed applications, APIs, and microservices to identify vulnerabilities before real attackers do.

This agent mimics external and internal threat actors, performing automated recon, enumeration, injection, fuzzing, and exploit attempts. Its goal is not to just scan — but to exploit, validate, and report risk in a reproducible, traceable, and composable way.

✳️ Why This Agent Exists¶

"Shift-left security" is not enough — autonomous factories must self-harden by running AI-driven penetration tests on every release candidate and in every tenant-aware context.

🏗️ Position in the Agent System¶

The PenTest Agent operates after deployment in staging or secure sandboxes, often triggered automatically after:

✅ DevOps Architect Agent deploys to isolated environment
✅ Security Architect Agent finalizes policies (e.g., RBAC, ingress rules)
✅ Observability Agent is activated (to capture trace + telemetry of attacks)

It is part of the Security Execution Layer, downstream from architecture agents but upstream of remediation and human security review.

🔁 Activation Context¶

flowchart LR
  SD[🧱 Secure Deploy Trigger]
  SA[🔐 Security Architect Agent]
  DO[⚙️ DevOps Architect Agent]
  PA[🛡️ PenTest Agent]
  SE[🧑‍💻 Security Engineer Agent]

  SD --> PA
  SA --> PA
  DO --> PA
  PA --> SE

Hold "Alt" / "Option" to enable pan & zoom

🧩 What It Simulates¶

Threat Simulation	Purpose
External Adversary	Black-box testing from public ingress endpoints
Compromised Tenant	Insider threat across shared zones (multi-tenant abuse)
Authenticated Role Escalation	Token abuse, privilege misalignment
API Injection & Replay	OWASP top 10 attack emulation, token replay
Rate Limit Bypass	DDoS simulation, quota abuse, greedy service calls
Service-to-Service Lateral Movement	Probes across mesh boundaries, bypass attempts

🧭 Strategic Role in the Platform¶

Capability	Outcome
⚔️ Offensive testing	Autonomous penetration simulation
🔍 AI fuzzing	Finds novel, complex, unlisted input flaws
🧪 Self-verifying	Each exploit attempt logs traceId + result
🔁 Repeatable	Every finding includes replay instructions and PoC
🔒 Defense evaluation	Tests observability, alerting, and circuit breaker configs

✅ Summary¶

The Security Penetration Testing Agent is a post-deploy, self-validating, AI-powered attacker emulator
It ensures every tenant, release, and endpoint is stress-tested against real attack behaviors
Its outputs feed directly into:
🔧 Security Engineer Agent (for hardening fixes)
📉 Human Security Reviews (for signoff gates)
📊 Risk dashboards and compliance scorecards

🧭 Core Responsibilities¶

Responsibility	Description
Passive Recon & Surface Enumeration	Map domains, ports, protocols, DNS records, open endpoints, environment metadata.
Active Probing & Injection	Simulate common OWASP-style attacks: XSS, SQLi, SSRF, IDOR, command injection, etc.
Fuzz Testing	Mutate API inputs with AI-generated tokens to discover unexpected edge case behavior or crash surfaces.
Authenticated Abuse Simulation	Replay JWTs, escalate roles, impersonate tenants, simulate token theft and session fixation.
Rate Limit Bypass Attempts	Abuse APIs by sending burst traffic, fragmented payloads, or timing-based evasion strategies.
Multi-Tenant Policy Evaluation	Attempt cross-tenant access using encoded headers, path traversal, or shared tokens.
Exploit Proof Generation	Log PoCs: exact inputs, timing, authentication state, trace ID, and replay-ready curl examples.
Vulnerability Reporting	Output structured JSON and Markdown reports with CVE-style descriptions, risk scoring, fix suggestions.
Risk Scoring & Classification	Map findings to severity levels, OWASP categories, CVSS scores, and mitigation effort estimates.
Retest Remediated Findings	Automatically rerun failed exploits post-patch (or on redeploy) to validate security improvements.

🛠️ What It Builds During Execution¶

Asset	Use
`vuln-report.md`	Human-readable penetration test summary
`vuln-findings.json`	Structured, queryable findings for dashboards and agent consumption
`trace-log.txt`	Ordered timeline of attack vector, traceId, results, and system responses
`poc-artifacts/`	curl scripts, modified JWTs, body templates to reproduce bugs
`risk-matrix.yaml`	Aggregated risk per endpoint, tenant, and service component

🎯 Coverage Areas¶

Layer	Examples of Coverage
Application	XSS, CSRF, SSRF, insecure headers, unsafe redirects
API Layer	Broken authentication, rate limits, open APIs, excessive data exposure
Identity & Auth	Token tampering, privilege escalation, broken role isolation
Service Mesh	Bypass of internal-only services, unauthorized service discovery
DNS & Routing	Subdomain takeover, wildcard record misuse, CNAME hijacking
Ingress	Misconfigured gateways, non-TLS routes, over-permissive CORS
Egress	Insecure outbound calls, missing validations, SSRF to internal IPs

📌 Execution Requirements¶

Must operate in read-only, non-destructive mode unless explicitly allowed
Can simulate impact, but never delete, mutate, or destroy data
Must always inject traceId, actorType: pentest-agent, and PoC log reference into outbound payloads
Must obey system-wide rules for maxThreads, attackWindow, allowedDestinations, and sandboxMode

✅ Summary¶

The PenTest Agent is responsible for:

End-to-end adversarial simulation
Traceable, reproducible exploitation
Risk reporting and triage metadata
Autonomous retesting and regression check loops

It acts as the “red team in a box”, integrated directly into the ConnectSoft autonomous pipeline.

📂 Inputs¶

Input Artifact	Source	Description
`openapi.yaml`	API Gateway Architect Agent	Full API surface: paths, verbs, parameters, schemas.
`deployed-endpoints.json`	DevOps Architect Agent	All live service URLs by environment, zone, tenant.
`security-zones.yaml`	Security Architect Agent	Trust boundaries, isolation levels, public/private exposure flags.
`dns-map.yaml`	Network Architect Agent	Tenant subdomains, internal-only FQDNs, exposed domains.
`auth-config.json`	Identity/Access Control Agent	Role hierarchy, token types, auth headers, session rules.
`rate-limit-policy.yaml`	Security Engineer Agent	Expected throttle rates, abuse patterns, expected defenses.
`egress-policy.yaml`	Network/Security Agents	Approved external calls to validate SSRF protections.
`known-cves.db`	MCP Vector Memory	Historical CVEs and exploit patterns for similar systems.
`sandbox-execution-config.json`	Orchestrator	Controls: scope, safe mode, duration, retry count, actor ID.

🧠 Optional Dynamic Inputs¶

Source	Description
`tenant-tokens.json`	Token broker or test tenant creation script	Simulated tokens for impersonation, escalation attempts.
`observability-hooks.json`	Trace injectors for outbound test traffic	Ensure all attacks are observable (`traceId`, `actorType`)
`test-user-matrix.yaml`	Credential and role permutations	Used for authenticated and privilege-based attack simulation

📘 Example Input Snippet: `deployed-endpoints.json`¶

{
  "booking-api": {
    "env": "staging",
    "tenant": "vetclinic-premium",
    "url": "https://booking.vetclinic.connectsoft.app",
    "ingressType": "public",
    "authRequired": true
  },
  "internal-analytics": {
    "env": "staging",
    "zone": "metrics",
    "url": "http://analytics.core.internal",
    "ingressType": "mesh-only"
  }
}

📘 Example Input Snippet: `auth-config.json`¶

{
  "tokenType": "JWT",
  "audience": "connectsoft-api",
  "roles": ["user", "admin", "superadmin"],
  "headers": {
    "Authorization": "Bearer <TOKEN>",
    "X-Tenant-Id": "vetclinic-premium"
  }
}

📥 Embedded Prompt Context (via Orchestrator)¶

intent: "Run authenticated and anonymous API penetration tests across staging zone"
focusAreas:
  - "privilege escalation"
  - "rate limit bypass"
  - "OWASP A5 - Broken Access Control"
maxExecutionTime: "12 minutes"
sandboxMode: true

✅ Summary¶

The PenTest Agent ingests inputs from:

🔐 Security blueprints (zones, tokens, rate limits)
🌐 Gateway definitions (OpenAPI, DNS, routing)
🔍 Observability metadata (for trace linking)
🧪 Credential/test harness (for multi-role abuse attempts)

These inputs enable precise, scoped, multi-tenant attack simulation, while respecting safety and traceability policies.

📦 Outputs Produced¶

Artifact	Format	Description
`vuln-findings.json`	JSON	Canonical machine-readable vulnerability report (traceable, reproducible, linked to APIs).
`vuln-report.md`	Markdown	Human-friendly penetration test summary with risk highlights and remediation paths.
`poc-artifacts/`	Directory	Contains PoC data: curl scripts, modified tokens, body payloads, screenshots, logs.
`trace-log.txt`	Plaintext	Ordered log of test execution: URLs tested, methods, auth state, response code, exploit success/failure.
`risk-matrix.yaml`	YAML	Heatmap of affected modules, tenants, CVSS-style severity, and potential impact scores.
`pentest-execution-metadata.json`	JSON	Metadata: `traceId`, `sessionId`, `targetUrl`, `authMode`, `agentId`, `executionWindow`.

📘 Sample: `vuln-findings.json`¶

[
  {
    "id": "CSP-2025-001",
    "service": "booking-api",
    "url": "https://booking.vetclinic.connectsoft.app/api/appointments",
    "method": "GET",
    "vulnerability": "Broken Access Control",
    "owaspCategory": "A5",
    "severity": "High",
    "tenant": "vetclinic-premium",
    "reproducible": true,
    "poc": "curl -H \"Authorization: Bearer adminToken\" ...",
    "traceId": "pentest-713-045a",
    "recommendation": "Apply RBAC enforcement on tenant context"
  }
]

📘 Sample: `vuln-report.md`¶

# ConnectSoft Security Penetration Test Report

**Target:** https://booking.vetclinic.connectsoft.app  
**Environment:** Staging  
**Session:** pentest-713-045a  
**Executed By:** PenTest Agent v1.4

---

## 🚨 Critical Findings

### 1. Broken Access Control – Booking API
- **Type:** A5 – OWASP Broken Access Control
- **Risk:** Admin can view another tenant’s data
- **Reproducible:** Yes
- **PoC:** See `poc-artifacts/CSP-2025-001-curl.txt`
- **Suggested Fix:** RBAC middleware injection

### 2. Rate Limit Bypass – Auth Endpoint
- Able to brute-force login tokens after bypassing rate limiter

📘 Sample: `risk-matrix.yaml`¶

services:
  booking-api:
    critical: 1
    high: 2
    medium: 0
    low: 1
tenants:
  vetclinic-premium:
    impactScore: 8.7
    affectedEndpoints: 3
global:
  riskScore: 7.1
  coverage: 84%
  confidence: 0.92

📦 Trace-Linked Metadata¶

{
  "traceId": "pentest-713-045a",
  "agentId": "penetration-testing-agent@v1.4",
  "authMode": "multi-role",
  "durationSec": 742,
  "scanDepth": "aggressive",
  "env": "staging"
}

🧠 Artifacts Consumed By¶

Agent	Usage
Security Engineer Agent	Builds patches, issue tickets, regression tests
Security Architect Agent	Updates Zero Trust model and policies
DevOps Architect Agent	Blocks deployment on risk threshold breach
Studio Dashboards	Visualize risks, heatmaps, attack graphs
HumanOps Agent	Alerts or routes security incidents for escalation

✅ Summary¶

The PenTest Agent outputs:

Human-readable and machine-consumable vulnerability reports
Proof-of-concept artifacts for replay and regression testing
Trace-aligned logs and metadata for observability and forensic visibility

All outputs are GitOps-storable, CI-integrable, and compliance-auditable.

📚 Knowledge Base¶

Domain	Knowledge Source
OWASP Top 10	Static rules for A1–A10 injection paths, token replay, abuse scenarios
Common CVEs	Exploit chain patterns, SSRF-to-metadata escalations, JWT key confusion
Fuzzing Templates	Smart field mutators for strings, arrays, encodings, schema-extracted payloads
Multi-Tenant Exploits	Header-based impersonation, path traversal, shared resource leakage
Rate Limiting Bypass	Timed requests, fragmented bodies, token caching, X-Forwarded-For manipulation
Misconfigured CORS	Wildcard origins, non-standard headers, credential leaks
API Abuse Scenarios	Broken object-level authorization (BOLA), batch endpoint overuse, enum attacks
Auth Attack Tactics	Token swap, role elevation, refresh token replay, ID spoofing

🧠 Memory-Backed Recall¶

Scenario	Retrieved Pattern
Admin token exposed via verbose error logs	Similar case in `proj-529` with root cause: stack trace leak
OpenAPI-based fuzzing with success	Pattern retrieved from `petco-billing-staging`, matched with 0.91 confidence
DNS CNAME takeover vector	Previously seen in `legacy-blog-vnet`, marked as unresolved in prior tests

→ These patterns influence which endpoints to prioritize and which test strategies to escalate.

🧩 Fuzzing Strategy Knowledge¶

Pattern	Example Behavior
Recursive Payload Injection	`"input": "${{7*7}}"` → tests server-side eval
Nested Object Overload	`{"profile":{"address":{"street":{"number":{"sub":...}}}}}`
Boundary Overflows	0-byte + 1MB payloads on upload APIs
JWT Mutation	Swap algorithm to `none`, tamper payload, try expired tokens
Encoding Confusion	Double URL encoding, base64 injection in fields like `X-Forwarded-For`

📘 CVE Pattern Extraction Example¶

exploitId: CVE-2023-11492
pattern:
  endpointMatch: "/api/invoices"
  method: POST
  mutationType: "unauthorized role escalation"
  requiredRole: "user"
  achievedRole: "admin"
  exploitInput:
    token: <user-token>
    body: {"amount": 1000, "adminNotes": "exploit"}
  expectedResponse: 201

📦 Static vs. Dynamic Knowledge Usage¶

Type	Example	Use
Static	OWASP injection strings, JWT tampering logic	Always applied during baseline scan
Dynamic	Learnable fuzzing patterns per schema type	Applied via AI-based test planner
Contextual Recall	Prior vulnerabilities in `booking-api`	Adjusts test order and scope

🧠 Continuous Update Model¶

CVE signatures and OWASP rulebooks are versioned per scan session
Exploit memory is indexed in the MCP vector DB using:
- service name
- endpoint patterns
- auth mode
- tenant type
Updates to patterns trigger re-evaluation in post-patch retest mode

✅ Summary¶

The PenTest Agent blends static, AI-generated, and vector-retrieved knowledge
It pulls prior exploit patterns, adapts to schema shapes, and mutates payloads intelligently
This knowledge base enables smart prioritization, coverage-based fuzzing, and zero-day emulation

🧭 Process Flow¶

flowchart TD
    INIT["🚀 Trigger: StartAgentSession(PenTestAgent)"]
    ENUM["🔍 Passive Enumeration"]
    PROBE["🛠️ Active Probing & Injection"]
    EXPLOIT["⚔️ Exploitation & Fuzzing"]
    VALIDATE["🧪 Exploit Validation"]
    REPORT["📤 Generate Reports & Artifacts"]
    RETRY["🔁 Retest Loop (if enabled)"]

    INIT --> ENUM --> PROBE --> EXPLOIT --> VALIDATE --> REPORT
    REPORT --> RETRY

Hold "Alt" / "Option" to enable pan & zoom

🪜 Execution Phases Explained¶

Phase	Description
1. Passive Enumeration	Maps exposed endpoints, DNS, service mesh routes, OpenAPI specs, auth schemes, ingress controls.
2. Active Probing	Executes OWASP-style injection tests (XSS, SQLi, SSRF), header tampering, rate-limiting bypass attempts.
3. Exploitation & Fuzzing	Uses learned and memory-backed payloads to mutate API inputs, roles, tokens, paths.
4. Validation	Checks if exploit succeeded: status codes, data leakage, privilege escalation, response time anomalies.
5. Reporting	Emits `vuln-findings.json`, `vuln-report.md`, PoCs, risk matrix, and trace logs.
6. Retest Loop (optional)	Can be enabled to rerun failing exploits post-remediation (e.g., nightly or post-deploy).

🧠 Controlled Looping (Retry-Aware)¶

Each exploit has a confidenceScore, validated: true/false, and retry flag
If confidence < 0.75, the exploit is mutated and reattempted (up to maxRetries)
If still unresolved, emits:

{
  "event": "PenTestAmbiguityWarning",
  "reason": "Validation inconclusive, further review recommended",
  "traceId": "...",
  "agentId": "penetration-testing-agent"
}

🔗 Skill-to-Phase Mapping¶

Phase	Skills
Enumeration	`PassiveDnsEnum`, `OpenApiSurfaceMap`, `ZoneScopeAnalyzer`
Probing	`TokenReplaySkill`, `OWASPInjectorSkill`, `RateLimitBreakerSkill`
Exploitation	`APIFuzzerSkill`, `PrivilegeEscalationSimulator`, `HeaderBypassComposer`
Validation	`ExploitVerifier`, `TraceCorrelator`, `PoCResponseParser`
Reporting	`RiskScorerSkill`, `ReportEmitter`, `PoCBundleBuilder`
Retry	`ExploitRetryPlanner`, `PatchRetestSkill`

📋 Session Metadata Tracking (Every Phase)¶

Each phase adds to the shared pentest-execution-metadata.json:

{
  "currentPhase": "exploitation",
  "target": "https://booking.vetclinic.connectsoft.app",
  "authMode": "admin-token",
  "traceId": "pentest-713-045a",
  "skillId": "APIFuzzerSkill:v1.3.0",
  "elapsedSec": 201
}

🧠 Control Flow Modifiers¶

Flag	Effect
`sandboxMode: true`	Disables destructive operations
`allowReplay: false`	Prevents creation of PoC curl/scripts
`scanDepth: aggressive`	Enables fuzzing, auth bypass, time-based exploit paths
`authMode: none/user/admin`	Scope of abuse attempts based on roles
`maxExecutionTime: "10m"`	Bounded session guard

✅ Summary¶

The PenTest Agent executes a 5-phase attack simulation pipeline, ending in artifact-rich reporting
Each phase is observed, retry-aware, and skill-driven
It supports progressive escalation, coverage-based depth, and semantic retry flows

⚙️ Execution Phases (Step-by-Step)¶

This section provides a detailed breakdown of the PenTest Agent’s core phases — each mapped to semantic skills, attack modules, and observability hooks. These stages are executed in order unless explicitly skipped or disabled via session config.

🔍 Phase 1: Passive Enumeration¶

Action	Description
`PassiveDnsEnum`	Queries internal + public DNS to map all reachable FQDNs (per `dns-map.yaml`).
`OpenApiSurfaceMap`	Parses all OpenAPI specs (`openapi.yaml`) to extract all routes, parameters, and verbs.
`IngressClassifier`	Detects which routes are public, internal, mesh-only, or tenant-specific.
`AuthContextMapper`	Extracts all available roles, token types, and auth enforcement patterns.
`ZoneScopeAnalyzer`	Aligns endpoint exposure with zone isolation (`security-zones.yaml`).

→ Output: enumerated-surface.json

🛠️ Phase 2: Active Probing¶

Action	Description
`OWASPInjectorSkill`	Injects payloads for top OWASP attacks: XSS, SQLi, SSRF, IDOR, CSRF, BOLA, etc.
`TokenReplaySkill`	Replays valid/expired JWTs across endpoints with varying scopes/roles.
`RateLimitBreakerSkill`	Simulates burst attacks, slow POSTs, and concurrency overflows.
`CORSProbeSkill`	Detects permissive origins, credential leaks, and wildcard flaws.
`RedirectLoopTester`	Tries redirect chains and unsafe `Location` headers.

→ Trace: probe-phase.trace.log → Artifacts: poc-artifacts/injection/*.json

⚔️ Phase 3: Exploitation & Fuzzing¶

Action	Description
`APIFuzzerSkill`	Uses schema-derived mutations and memory-backed payloads to trigger crashes and data leaks.
`PrivilegeEscalationSimulator`	Swaps token roles and attempts to access protected resources.
`HeaderBypassComposer`	Builds crafted `X-Forwarded-For`, `X-Tenant-Id`, or `X-Role` headers.
`TenantCrossTalkSkill`	Sends encoded requests impersonating other tenants across zones.
`EgressEscalationTester`	Uses SSRF patterns to hit internal or unauthorized external addresses.

→ Artifacts: poc-artifacts/exploits/*.sh, jwt-modified.txt

🧪 Phase 4: Validation¶

Action	Description
`ExploitVerifier`	Confirms exploit success via status codes, response deltas, and trace logs.
`PoCResponseParser`	Extracts affected fields, error codes, stack traces, or leaked data.
`TraceCorrelator`	Maps each exploit to system trace spans using injected `traceId`, `actorType`.
`ImpactScorer`	Computes CVSS-like impact per finding and marks `validated: true/false`.

→ Output: vuln-findings.json, PoC summary table

📤 Phase 5: Reporting¶

Action	Description
`RiskScorerSkill`	Builds per-tenant, per-service risk scores and heatmaps.
`ReportEmitter`	Generates `vuln-report.md`, CVE-style output, and remediation tips.
`PoCBundleBuilder`	Saves scripts, curl files, modified tokens, and logs for reproduction.
`PentestMetadataExporter`	Writes metadata for orchestration and dashboard usage.

→ Output:

vuln-report.md
risk-matrix.yaml
pentest-execution-metadata.json

🔁 Optional Phase 6: Retest Loop¶

Action	Description
`ExploitRetryPlanner`	Re-attempts validated exploits after fixes or policy changes.
`PatchRetestSkill`	Confirms fixed APIs no longer allow prior abuse.
`RegressionTraceComparer`	Verifies PoC responses no longer match historical exploit pattern.

→ Triggered manually or automatically on redeploy

📎 Trace and Observability Links Per Phase¶

Each phase injects:

traceId, exploitId, authContext, zoneId, agentId
Metrics: pentest.findings.total, pentest.exploits.verified, pentest.success.ratio

All are exported to the Observability Agent and Studio dashboards.

✅ Summary¶

The agent runs 5+1 execution phases:

🔍 Surface enumeration
🛠️ Targeted probing
⚔️ Real exploitation
🧪 Automated validation
📤 Structured reporting
🔁 (Optional) post-fix retest

All phases are traceable, skill-driven, and reproducible.

🧠 Kernel Skills and Actions¶

The PenTest Agent is powered by a Semantic Kernel-based skill composition model, enabling it to execute complex, traceable, and reproducible penetration tests. These skills are modular, scoped by sessionId, and chained dynamically based on coverage depth, confidence levels, and past exploit success.

🔩 Core Kernel Skills¶

Skill Name	Purpose
`OpenApiSurfaceMap`	Parses OpenAPI documents to extract routes, input schemas, and authorization tags.
`PassiveDnsEnum`	Enumerates FQDNs from DNS map; identifies zone exposure (public/internal/mesh).
`OWASPInjectorSkill`	Performs rule-based injection attacks using OWASP Top 10 signatures (XSS, SQLi, CSRF, etc.).
`TokenReplaySkill`	Tests re-use of expired, downgraded, or modified JWTs across role-based endpoints.
`RateLimitBreakerSkill`	Sends burst traffic, slow POSTs, or header mutations to test abuse controls.
`APIFuzzerSkill`	Generates mutated input payloads based on API schemas and historical exploit memory.
`PrivilegeEscalationSimulator`	Crafts requests as lower-privileged roles to reach restricted actions.
`TenantCrossTalkSkill`	Simulates inter-tenant attacks using token swap, header spoofing, or path tampering.
`CORSProbeSkill`	Tests for misconfigured CORS (wildcard origins, open credentials, unsafe headers).
`PoCResponseParser`	Analyzes exploit responses for anomalies: stack traces, verbose errors, or data leakage.
`ExploitVerifier`	Checks exploit success by confirming state changes, error codes, or trace-based effects.
`RiskScorerSkill`	Assigns severity scores and CVSS-style impact labels per finding.
`ReportEmitter`	Generates `vuln-findings.json`, `vuln-report.md`, and `risk-matrix.yaml`.
`ExploitRetryPlanner`	Re-attempts validated exploits after a patch, upgrade, or redeploy event.

🔁 Composite Skill Chains¶

🛠️ Probing Chain¶

OpenApiSurfaceMap
→ TokenReplaySkill + OWASPInjectorSkill
→ RateLimitBreakerSkill
→ ExploitVerifier

⚔️ Exploitation Chain¶

APIFuzzerSkill
→ PrivilegeEscalationSimulator
→ PoCResponseParser
→ ExploitVerifier

📤 Reporting Chain¶

PoCResponseParser
→ RiskScorerSkill
→ ReportEmitter
→ PentestMetadataExporter

🧠 Skill Example: `OWASPInjectorSkill`¶

skill: OWASPInjectorSkill
attackVectors:
  - injectionType: "SQLi"
    payload: "' OR '1'='1"
    targetParam: "userId"
    context:
      authToken: "<JWT:user>"
      url: "/api/users/details"
      method: "POST"

📘 Skill Outputs (Standard Format)¶

{
  "skillId": "TenantCrossTalkSkill",
  "exploitId": "TCT-0453",
  "traceId": "pentest-713",
  "confidence": 0.88,
  "success": true,
  "pocArtifact": "poc-artifacts/TCT-0453-curl.txt"
}

⚙️ Skill Governance¶

Constraint	Enforced Behavior
`sandboxMode: true`	Disables mutation of persisted data (read-only PoC)
`authScope: limited`	Restricts skills like `PrivilegeEscalationSimulator`
`maxExecutionTime`	Pauses or skips deep fuzzing chains beyond allowed time
`traceId` injection	Every skill logs all outputs under unified trace scope
`memoryRecallEnabled`	If true, prior exploits influence skill planning (via MCP embeddings)

🔒 Safety Guards¶

Each skill checks for:
- Safe HTTP methods (GET, POST, not DELETE unless isolated sandbox)
- Role isolation violations (must not simulate real privilege escalation outside sandbox)
- Artifact emission boundaries (PoCReplay disabled if replayAllowed = false)

✅ Summary¶

The PenTest Agent is powered by a modular Semantic Kernel skill graph that:

Covers recon, probing, injection, abuse, validation, and reporting
Follows safety-first, zero-trust, and tenant-aware principles
Adapts skill chaining based on exploit results, confidence, and memory recall

🗣️ System Prompt¶

The System Prompt defines the persona, role boundaries, and execution constraints for the PenTest Agent. It is injected during agent bootstrap by the Orchestrator, ensuring the agent:

Knows its scope of authority
Enforces security-first, observability-first principles
Aligns with ConnectSoft’s multi-tenant, composable architecture

🧠 System Prompt Template¶

You are the Security Penetration Testing Agent in the ConnectSoft AI Software Factory.

Your mission is to autonomously simulate real-world attacker behavior against deployed systems
to discover vulnerabilities before they are exploited in production.

You must operate within a secure, traceable, non-destructive environment unless explicitly authorized.

Your responsibilities include:
- Surface enumeration using public and internal FQDNs
- API probing and fuzzing using OpenAPI schemas and authentication tokens
- Simulation of OWASP Top 10 attacks and CVE pattern matches
- Validation of exploit success via HTTP responses, headers, data leakage, and timing
- Privilege escalation attempts, tenant impersonation, and CORS bypass checks
- Reporting validated vulnerabilities as PoC artifacts, JSON findings, and Markdown summaries

You must:
- Annotate every action with `traceId`, `authContext`, `zoneId`, and `tenantId`
- Emit `vuln-findings.json`, `vuln-report.md`, `poc-artifacts/`, and `risk-matrix.yaml`
- Use memory embeddings of past exploits if available via MCP
- Re-run previously validated findings after deployment patch (if configured)

NEVER mutate production data, delete records, or perform non-permitted destructive actions.

Operate in **Zero Trust by default**, isolate tenants, enforce scope, and ensure reproducibility.

Collaborate with:
- Security Architect Agent for trust zones and mTLS definitions
- DevOps Agent for deployed endpoints
- Observability Agent for trace capture
- Security Engineer Agent for remediation workflows

You are a red-team-in-a-box agent. Be surgical, reproducible, and self-validating.

🔐 Prompt Role Definition¶

Section	Intent
🎯 Mission	Defines agent as attacker simulator and exploit validator
🔒 Constraints	Forces Zero Trust, sandbox-only mode unless authorized
📤 Outputs	Enforces emission of PoCs, risk scoring, and full trace metadata
🧠 Knowledge Use	Encourages use of semantic memory and skill planning
🤝 Collaboration	Explicitly calls downstream and adjacent agents
❗ Forbidden Actions	Disallows unsafe behavior, ensures runtime safety and auditability

📘 Safety Statements¶

Required for compliance with:
- SOC 2 / ISO 27001 scan boundaries
- ConnectSoft’s Security-First and Multi-Tenant Principles
- GitOps reproducibility and non-destructiveness

✅ Summary¶

The System Prompt:

Establishes the PenTest Agent’s operational contract
Defines allowed and disallowed behavior
Sets the standard for traceability, reproducibility, and safety
Aligns agent execution with ConnectSoft’s composable, tenant-isolated, AI-native security model

🧾 Input Prompt Template¶

The Input Prompt Template defines how the Orchestrator or upstream agents instruct the PenTest Agent. It encapsulates all necessary context — such as API targets, tenant scope, test depth, and execution policies — to enable the agent to run a controlled, reproducible, and traceable penetration session.

📥 Standard YAML Input Format¶

traceId: pentest-713-v1
sessionId: penetration-test-session-045a
projectId: proj-713
environment: staging
authModes:
  - user-token
  - admin-token
targets:
  - name: booking-api
    url: https://booking.vetclinic.connectsoft.app
    tenantId: vetclinic-premium
    zone: core
    openApiSpec: ./openapi/booking-api.yaml
    ingressType: public
  - name: analytics-service
    url: http://analytics.internal.svc.cluster.local
    tenantId: system
    zone: metrics
    ingressType: mesh-only
sandboxMode: true
scanDepth: aggressive
maxExecutionTime: 12m
replayEnabled: true
memoryRecallEnabled: true
exploitReplayAllowed: false
triggerOnDeploy: true
allowedAttackTypes:
  - owasp
  - auth-bypass
  - fuzzing

🧠 Key Fields Explained¶

Field	Purpose
`traceId`, `sessionId`	Full execution traceability
`targets[]`	API endpoints to attack with context: URL, tenant, ingress, OpenAPI spec
`authModes[]`	Tokens or roles under which to simulate attack (e.g., user, admin, guest)
`sandboxMode`	If `true`, prevents data mutations or real destructive operations
`scanDepth`	`basic`, `full`, or `aggressive` — controls skill chaining and fuzzing intensity
`maxExecutionTime`	Prevents overuse of resources or infinite loops in fuzzing
`memoryRecallEnabled`	Enables semantic memory lookup of prior vulnerabilities and attack patterns
`exploitReplayAllowed`	If `true`, emits curl or script artifacts to reproduce vulnerabilities
`allowedAttackTypes`	Enables focused attack paths (e.g., `owasp`, `fuzzing`, `token-replay`)

📋 Example Input Fragment (Authentication & Role Abuse Focus)¶

targets:
  - name: invoice-api
    url: https://billing.vetclinic.connectsoft.app/api/invoices
    tenantId: vetclinic-premium
    openApiSpec: ./openapi/invoice-api.yaml
authModes:
  - jwt-user
  - jwt-admin
allowedAttackTypes:
  - privilege-escalation
  - token-swap
  - session-fixation
scanDepth: full
sandboxMode: true

📎 Orchestrator JSON Wrapper¶

{
  "agentId": "penetration-testing-agent",
  "inputFormat": "yaml",
  "payload": "see attached yaml",
  "policy": {
    "retryOnFailure": true,
    "blockOnHighRisk": true,
    "escalateOnAmbiguity": true
  }
}

🧠 Optional Enhancers¶

Enhancer	Description
`observabilityHooks`	Defines how to inject `traceId`, `zoneId`, `actorType` into each request
`rateLimitExpectations.yaml`	Used for validating DoS-resilience
`testUserMatrix.yaml`	Provides sample users and credentials for impersonation tests
`known-vulnerabilities.vector`	MCP lookup vector for exploit pattern recall

✅ Summary¶

The input template uses a structured YAML schema plus optional JSON orchestrator wrapper
It defines attack scope, constraints, targets, and roles
Enables repeatable, safe, and fully observable execution flows

📤 Output Format and Structure¶

The PenTest Agent produces structured, multi-format, reproducible, and traceable output artifacts. These outputs are designed for both automated downstream agents and human security analysts, following ConnectSoft's principles of observability, reproducibility, and GitOps-ready documentation.

📁 Output Directory Layout¶

/pentest-results/
  vuln-findings.json
  vuln-report.md
  risk-matrix.yaml
  poc-artifacts/
    CSP-2025-001-curl.txt
    TCT-0453-curl.sh
  trace-log.txt
  pentest-execution-metadata.json

📦 Artifact Details¶

🔹 `vuln-findings.json` (Primary machine-readable output)¶

[
  {
    "id": "CSP-2025-001",
    "service": "booking-api",
    "url": "https://booking.vetclinic.connectsoft.app/api/appointments",
    "method": "GET",
    "vulnerability": "Broken Access Control",
    "owaspCategory": "A5",
    "severity": "High",
    "tenant": "vetclinic-premium",
    "validated": true,
    "reproducible": true,
    "traceId": "pentest-713-045a",
    "exploitId": "EXP-045a-bac",
    "pocArtifact": "poc-artifacts/CSP-2025-001-curl.txt",
    "recommendation": "Enforce RBAC checks on token-scoped tenantId"
  }
]

🔹 `vuln-report.md` (Human-readable executive summary)¶

# ConnectSoft Penetration Test Report

**Session:** pentest-713-045a  
**Environment:** staging  
**Target Tenant:** vetclinic-premium  
**Scan Depth:** aggressive  
**Findings:** 3 confirmed, 2 high risk, 1 critical

---

## 🔐 Confirmed Critical Issue

### 🔸 Broken Access Control – Booking API
- **PoC:** See CSP-2025-001-curl.txt
- **Severity:** High
- **Risk:** Admin users can impersonate other tenants via token swap
- **Fix:** Validate `X-Tenant-Id` vs. JWT claim in middleware

🔹 `risk-matrix.yaml`¶

services:
  booking-api:
    critical: 1
    high: 2
    medium: 1
  internal-analytics:
    high: 1
tenants:
  vetclinic-premium:
    totalFindings: 3
    riskScore: 8.2
global:
  totalFindings: 4
  riskScore: 7.1
  coverage: 86%

🔹 `poc-artifacts/`¶

Each file contains exact exploit vectors:

Modified tokens (.jwt)
curl or httpie commands
Full response snapshots (status code, headers, body)
Time of exploit, session trace ID

Example file: CSP-2025-001-curl.txt

curl -H "Authorization: Bearer admin-token" \
     -H "X-Tenant-Id: vetclinic-premium" \
     https://booking.vetclinic.connectsoft.app/api/appointments/42

🔹 `trace-log.txt`¶

Chronological log of attack attempts with:

URL
Auth context
Payload reference
Skill invoked
Result: success, blocked, retry

🔹 `pentest-execution-metadata.json`¶

{
  "traceId": "pentest-713-045a",
  "sessionId": "penetration-session-001",
  "agentId": "penetration-testing-agent@1.4",
  "authModes": ["user-token", "admin-token"],
  "sandboxMode": true,
  "exploitReplayAllowed": false,
  "coverageScore": 84,
  "confidence": 0.93,
  "completedAt": "2025-05-14T18:24:33Z"
}

✅ Output Expectations Summary¶

Property	Enforcement
Reproducibility	Each exploit must include a PoC or retry instruction
Traceability	Every finding is mapped to `traceId`, `authMode`, and `exploitId`
Severity Scoring	CVSS-style metrics: `riskScore`, `coverage`, `impactLevel`
Machine & Human Ready	JSON for agents; Markdown + curl for humans
Retest-Ready	PoC structure allows rerun on redeploy or patch cycle

🧠 Memory¶

The PenTest Agent uses both short-term contextual memory and long-term semantic memory to enhance its attack logic, recall prior exploit patterns, and support reproducible, intelligent penetration testing across projects and releases.

These memory layers enable the agent to operate as an adaptive red team unit, not just a static scanner.

🧠 Memory Types¶

Type	Description	Backed By
Short-Term Session Memory	In-memory during execution session. Tracks roles, tokens, endpoint states, past skill results.	SK context memory
Long-Term Exploit Memory	Stores confirmed vulnerabilities, exploit vectors, and CVSS scores for reuse across environments or tenants.	Vector DB via MCP server
Artifact History Memory	Index of previously emitted artifacts: PoCs, reports, DNS & endpoint mappings.	GitOps repo or blob store
Fuzzing Pattern Memory	Recall of successful fuzzing mutations and schema alignments.	SK memory + semantic recall embeddings
Remediation Validation Cache	Remembers vulnerabilities previously fixed, for retest comparisons.	JSON diff cache with `vulnId`, `status`

🔄 Memory Use in Execution Flow¶

Phase	Memory Role
🔍 Enumeration	Match OpenAPI shape to known vulnerable schemas or surface layouts
🛠️ Probing	Recall bypass patterns or header manipulations that worked on similar endpoints
⚔️ Exploitation	Reuse PoC inputs from previous attacks on this tenant or service group
🧪 Validation	Compare response patterns to previous exploit logs for drift or regression
📤 Reporting	Embed links to past reports or changes in `riskScore`, severity, or coverage %

🧠 Example: Vector Memory Recall¶

{
  "query": "POST /api/invoices using Bearer token with amount",
  "match": {
    "exploitId": "EXP-0412",
    "vulnerability": "Authorization Bypass via Body Field",
    "tenant": "petco-enterprise",
    "confidence": 0.92
  },
  "recommendation": "Re-try modified body field with role=admin"
}

🧾 Fuzzing Memory Example¶

Input Type	Last Success
`phoneNumber`	Double URL-encoded string caused crash
`JWT`	Alg=none accepted on legacy endpoint
`Address`	Nested object overflow exposed validation bypass

→ If schema pattern matches, these fuzz vectors are reused (unless marked patched: true).

📘 Retest Memory Model¶

{
  "exploitId": "CSP-2025-001",
  "status": "fixed",
  "retestAttempted": true,
  "retestResult": "blocked",
  "lastSuccess": "2025-04-01",
  "lastFail": "2025-05-10"
}

→ Retest flag is set, diff is noted, and resolution score updated.

🔐 Scoped Memory Access¶

Scope	Access Level
Same tenant, same environment	Full recall allowed
Cross-tenant, same blueprint	Allowed for exploit pattern lookup only
External workspace	Not permitted unless explicitly shared via MCP

✅ Summary¶

The PenTest Agent uses multi-layered memory for smart reuse, regression validation, and attack tuning
Memory allows:
- 🔁 Retesting of known exploits
- 🧠 Schema-aware fuzzing improvements
- 📉 Drift detection in auth/config across releases
All memory access is trace-scoped and tenant-aware, preserving isolation

✅ Validation Rules¶

Validation is a critical function of the PenTest Agent. It ensures that:

Detected vulnerabilities are real (not false positives)
Every exploit is reproducible and observable
Risk levels are appropriately classified
Findings meet the ConnectSoft standard for quality, traceability, and non-disruption

🧪 What Gets Validated¶

Validation Area	Purpose
Exploit Success Criteria	Ensure that each exploit resulted in a measurable unauthorized outcome (status code, leaked data, privilege escalation).
Trace Correlation	Confirm exploit can be traced using `traceId`, `actorType`, and appears in observability logs.
Reproducibility	Validate that each vulnerability is accompanied by a PoC that can be rerun with the same result.
Non-Destructiveness	Confirm that no destructive changes (deletion, mutation) occurred unless explicitly enabled.
Isolation Boundaries	Ensure attacks did not cross tenant or zone boundaries unintentionally.
Impact Accuracy	Match observed outcome to OWASP or CVSS scoring criteria for proper risk labeling.
Fuzzing Coverage	Ensure payloads cover all OpenAPI fields and reach at least 80% of endpoints under test.

🧠 Exploit Validation Workflow¶

flowchart TD
    A[Exploit Sent]
    B{Success Response?}
    C{Trace Captured?}
    D{Replay Matches?}
    E{Tenant Scope Valid?}
    F[Mark Validated]
    G[Flag as Inconclusive]

    A --> B
    B -- Yes --> C
    C -- Yes --> D
    D -- Yes --> E
    E -- Yes --> F
    E -- No --> G
    D -- No --> G
    C -- No --> G
    B -- No --> G

Hold "Alt" / "Option" to enable pan & zoom

📘 Validation Metadata Example¶

{
  "exploitId": "EXP-0453",
  "validated": true,
  "reproducible": true,
  "traceCorrelated": true,
  "authContext": "admin-token",
  "tenantId": "vetclinic-premium",
  "cvssScore": 8.6,
  "owaspCategory": "A5 - Broken Access Control"
}

🚨 Validation Failure Examples¶

Condition	Outcome
No `traceId` match in observability	Finding marked `inconclusive`, not emitted
PoC fails to reproduce in replay	Risk score downgraded; `reproducible: false`
Exploit spans tenants	Validation fails unless `multi-tenant test mode` is enabled
CORS misconfig detected, but no leak	Finding emitted as `low` severity with `impact: informational`

🧾 Severity & Risk Validation Matrix¶

Condition	CVSS Score	Risk Level
Full tenant compromise	9.0+	Critical
Role escalation (admin from user)	8.0+	High
Token replay with mild abuse	6.0+	Medium
CORS misconfig with no data leak	4.0–5.9	Low
Info-only finding (headers, error detail)	<4.0	Informational

🔁 Retest Validation (Post-Patch)¶

If exploit marked fixed, agent:
- Reruns PoC
- Compares new response body/hash to prior exploit result
- Updates finding status (status: resolved or regressed)

✅ Summary¶

Every PenTest finding must pass multi-stage validation before inclusion:
- Confirmed success
- Trace alignment
- Replayable PoC
- Risk scoring
Invalid or inconclusive results are not reported unless flagged for human review
Validation logic is automated, observable, and tenant-aware

🔄 Retry / Correction Flow¶

The PenTest Agent is designed to be self-healing, retry-aware, and confidence-driven. When an attack attempt fails validation, results in ambiguity, or produces insufficient confidence, the agent automatically enters a retry or correction loop — unless constrained by time or policy.

🔁 Retry Triggers¶

Condition	Action Taken
`confidenceScore < 0.75`	Rerun with modified payloads, alternate token scopes, or fuzzing pattern
`trace correlation missing`	Reinserts trace headers and retries exploit with observability hooks
`PoC failed to reproduce`	Adjusts request (e.g., timing, encoding) and retries 1–2 times
`tenant boundary violated`	Reduces scope and reruns with narrowed zone or token
`scan depth incomplete`	Triggers exploratory retry with deeper schema fuzzing
`rate limit blocked`	Waits + replays with backoff window or alternate header spoofing

🧠 Retry Strategy Hierarchy¶

flowchart TD
    A[Initial Exploit Attempt]
    B{Validated?}
    B -- Yes --> C[Store & Report]
    B -- No --> D{Retry Budget Available?}
    D -- Yes --> E[Mutate & Retry via RetryPlanner]
    D -- No --> F[Emit Ambiguity Warning]

    E --> B
    F --> G[Log as Inconclusive or Raise for Human Review]

Hold "Alt" / "Option" to enable pan & zoom

🔧 Mutation Techniques Used in Retry¶

Retry Strategy	Mutation Example
Header Tweaks	Modify or drop `X-Tenant-Id`, inject `X-Forwarded-For`
Token Replays	Try expired, swapped, tampered JWTs
Schema Variations	Add unknown fields, mutate enums, force arrays to scalars
Time-based Replay	Wait for retry window or execute outside known throttle window
Encoding	Apply double URL encoding, base64 payload wrapping

📋 Retry Metadata¶

Each retry is tracked and emitted in logs and metadata:

{
  "exploitId": "EXP-0453",
  "retryAttempt": 2,
  "lastConfidence": 0.81,
  "mutationStrategy": "TokenRoleSwap + DoubleEncoding",
  "resolved": true,
  "finalStatus": "validated"
}

❗ Max Retry Control¶

Parameter	Description
`maxRetriesPerExploit`	Default: 2 attempts
`retryOnTraceFailure`	`true` → allows up to 1 retry if trace headers were missing
`retryConfidenceThreshold`	Below this (e.g., 0.6), exploit is skipped unless human review is enabled
`retryTimeoutMs`	Guards against excessive time waste on retry attempts

📢 Events Triggered by Retry Outcomes¶

Event	When Emitted
`ExploitRetryAttempted`	Any retry starts
`ExploitRetrySucceeded`	Retry confirmed a previously invalid exploit
`ExploitRetryFailed`	Retry exceeded limit without resolution
`PenTestAmbiguityWarning`	Retry ended with inconclusive result

🔐 Scope Safety in Retry¶

NEVER expands attack surface
Always uses original authModes, zone, sandboxMode constraints
Cannot escalate privileges beyond allowed context (e.g., simulate admin when only user mode is given)

✅ Summary¶

The PenTest Agent uses a controlled, traceable retry engine with mutation strategies
Retries are:
- 📊 Metrics-tracked
- 🧠 Memory-informed
- 🔒 Scope-safe
If ambiguity remains, findings are flagged for review, not silently emitted

🤝 Collaboration Interfaces¶

The PenTest Agent is part of the Security Execution Layer and operates in close coordination with architecture, deployment, observability, and human oversight agents. It consumes deployment- and config-level inputs, and produces actionable outputs for remediation, policy adjustment, and risk visualization.

🔗 Core Agent Collaborations¶

Agent	Interaction	Description
Security Architect Agent	Input provider	Supplies `security-zones.yaml`, mTLS configs, trust boundaries for scoped attack planning.
DevOps Architect Agent	Input provider	Provides deployed endpoints, ingress modes, and API readiness flags.
API Gateway Architect Agent	Input provider	Exposes `openapi.yaml`, route headers, auth decorators, and public-facing path maps.
Security Engineer Agent	Output consumer	Uses `vuln-findings.json`, `risk-matrix.yaml`, and PoCs to write patches and regression tests.
Observability Agent	Trace partner	Injects trace context for exploit detection and logs test coverage in metrics.
HumanOps Agent	Escalation path	Reviews ambiguous or high-impact findings (e.g., unresolved tenant impersonation).
Studio UI (Security Dashboard)	Visualization consumer	Displays risk matrix, heatmaps, PoC diff timelines, CVE coverage progress.

📤 Emitted Events for Collaboration¶

Event	Description	Consumed By
`NetworkTopologyReady`	Signals environment ready for attack simulation	PenTest Agent (trigger)
`PenTestStarted`	Signals new execution session has begun	Observability Agent, HumanOps
`PenTestCompleted`	Session ended; outputs are available	Security Engineer Agent, Studio
`VulnerabilityDiscovered`	A high/critical finding validated	Security Engineer Agent, Orchestrator
`PenTestAmbiguityWarning`	Unvalidated exploit (trace, auth, or coverage issue)	HumanOps, Orchestrator
`RetestResultsUpdated`	Retest after fix; confirms resolution or regression	Security Engineer Agent

🧩 Collaboration Workflow Example¶

sequenceDiagram
    participant DO as DevOps Agent
    participant GW as API Gateway Architect
    participant SA as Security Architect
    participant PT as 🛡️ PenTest Agent
    participant SE as Security Engineer
    participant OBS as Observability Agent

    DO->>PT: deployed-endpoints.json
    GW->>PT: openapi.yaml
    SA->>PT: security-zones.yaml
    PT->>OBS: emit trace headers on all outbound requests
    PT->>SE: vuln-findings.json, risk-matrix.yaml
    PT->>Studio: vuln-report.md

Hold "Alt" / "Option" to enable pan & zoom

Artifact	Shared With	Purpose
`vuln-findings.json`	SE Agent, Studio, Orchestrator	Source of truth for confirmed exploits
`poc-artifacts/`	SE Agent, HumanOps (if allowed)	Used for replay and regression validation
`risk-matrix.yaml`	Studio Dashboard	Heatmap + risk scoring visualizations
`pentest-execution-metadata.json`	All agents	Traceability, reproducibility, and lineage linking

🔐 Access Governance¶

Tenants never share PoCs unless cross-tenant testing is explicitly enabled
All artifact access is scoped by:
- tenantId
- sessionId
- traceId
- agentRole

✅ Summary¶

The PenTest Agent relies on upstream configurations from deployment and gateway agents
It feeds security outputs to engineers, observability tooling, and studio visualizations
Collaboration is event-based, trace-scoped, and fully aligned with ConnectSoft's composable agent architecture

🔎 Observability & Human Intervention Hooks¶

The PenTest Agent is fully instrumented for observability, traceability, and human-in-the-loop review. Every action — from test planning to exploit replay — is logged, traced, and surfaced through dashboards and event streams. When ambiguity arises or high-impact issues are found, the agent can escalate findings for manual validation or override.

📊 Observability Features¶

Feature	Description
OpenTelemetry Tracing	Each exploit attempt, retry, skill invocation, and finding validation emits `traceId`, `spanId`, and `agentId`.
Structured Logs	JSON logs include skill name, target URL, tenantId, authMode, payload class, exploitId, result.
Metrics Export	Emits Prometheus-style metrics like `pentest.exploits.total`, `pentest.risk.high`, `coverage.ratio`, `confidence.avg`.
Session Metadata Stream	All sessions emit `pentest-execution-metadata.json`, retrievable by Orchestrator and dashboards.

📈 Example Exported Metrics¶

pentest.exploits.validated: 6
pentest.exploits.ambiguous: 2
pentest.retries.total: 9
pentest.coverage.percent: 84.5
pentest.riskScore.global: 7.3
pentest.findings.high: 2

🖥️ Studio Dashboard Integration¶

The following views are available in Studio:

🔍 Trace Explorer: Browse all attack paths per traceId, exploitId, authContext
🗺️ Risk Heatmap: Per-tenant/service severity grid
📈 Scan History Timeline: Compare findings over time
🧪 PoC Viewer: See past curl/token/script artifacts (with redaction for sensitive items)
🚦 Gate Status: Release blocker if high/critical unresolved findings exist

⚠️ Human Intervention Hooks¶

Scenario	Trigger	Escalation Target
`confidenceScore < 0.6` and `validated: false`	Inconclusive exploit result	`HumanOps Agent` or Studio dashboard review
`cross-tenant data exposure detected`	Tenant boundary violation	`Security Architect Agent` and `HumanOps Agent`
`PoC fails to reproduce after retry`	Regression suspicion	`Security Engineer Agent` for manual patch check
`rate-limit blocked probe consistently`	Potential misclassified 429 → human input to bypass
`dangerous exploit (e.g., delete)` requires override	`destructiveMode: false`	Require `manualOverride = true` in execution config

🛠️ Manual Override Example¶

{
  "event": "PenTestManualReviewRequired",
  "reason": "Detected privilege escalation but trace missing",
  "requiresApproval": true,
  "traceId": "pentest-713-v1",
  "artifactUri": "poc-artifacts/CSP-2025-001-curl.txt"
}

→ Handled by a human agent or security reviewer via Studio.

🔁 Feedback Loop from Reviewers¶

Upon human approval or rejection:

Finding is either:
- Confirmed and locked in as validated: true
- Dismissed and tagged with reviewResolution: falsePositive
Status is reflected in dashboards and in vuln-findings.json with reviewer name, timestamp, and decision rationale.

✅ Summary¶

The PenTest Agent is observability-first:
- Full telemetry and metrics
- Trace-spanned exploit logic
- Real-time dashboards and logs
Human review is supported when:
- 🔍 Confidence is low
- ⚠️ Risk is high
- ❗Scope violations are suspected
Studio and downstream agents are fully integrated for remediation, visibility, and control

🛡️ Security Penetration Testing Agent Specification¶

🧠 Purpose¶

✳️ Why This Agent Exists¶

🏗️ Position in the Agent System¶

🔁 Activation Context¶

🧩 What It Simulates¶

🧭 Strategic Role in the Platform¶

✅ Summary¶

🧭 Core Responsibilities¶

🛠️ What It Builds During Execution¶

🎯 Coverage Areas¶

📌 Execution Requirements¶

✅ Summary¶

📂 Inputs¶

🧠 Optional Dynamic Inputs¶

📘 Example Input Snippet: deployed-endpoints.json¶

📘 Example Input Snippet: auth-config.json¶

📥 Embedded Prompt Context (via Orchestrator)¶

✅ Summary¶

📦 Outputs Produced¶

📘 Sample: vuln-findings.json¶

📘 Sample: vuln-report.md¶

📘 Sample: risk-matrix.yaml¶

📦 Trace-Linked Metadata¶

🧠 Artifacts Consumed By¶

✅ Summary¶

📚 Knowledge Base¶

🧠 Memory-Backed Recall¶

🧩 Fuzzing Strategy Knowledge¶

📘 CVE Pattern Extraction Example¶

📦 Static vs. Dynamic Knowledge Usage¶

🧠 Continuous Update Model¶

✅ Summary¶

🧭 Process Flow¶

🪜 Execution Phases Explained¶

🧠 Controlled Looping (Retry-Aware)¶

🔗 Skill-to-Phase Mapping¶

📋 Session Metadata Tracking (Every Phase)¶

🧠 Control Flow Modifiers¶

✅ Summary¶

⚙️ Execution Phases (Step-by-Step)¶

🔍 Phase 1: Passive Enumeration¶

🛠️ Phase 2: Active Probing¶

⚔️ Phase 3: Exploitation & Fuzzing¶

🧪 Phase 4: Validation¶

📤 Phase 5: Reporting¶

🔁 Optional Phase 6: Retest Loop¶

📎 Trace and Observability Links Per Phase¶

✅ Summary¶

🧠 Kernel Skills and Actions¶

🔩 Core Kernel Skills¶

🔁 Composite Skill Chains¶

🛠️ Probing Chain¶

⚔️ Exploitation Chain¶

📤 Reporting Chain¶

🧠 Skill Example: OWASPInjectorSkill¶

📘 Skill Outputs (Standard Format)¶

⚙️ Skill Governance¶

🔒 Safety Guards¶

✅ Summary¶

🗣️ System Prompt¶

🧠 System Prompt Template¶

🔐 Prompt Role Definition¶

📘 Safety Statements¶

✅ Summary¶

🧾 Input Prompt Template¶

📥 Standard YAML Input Format¶

🧠 Key Fields Explained¶

📋 Example Input Fragment (Authentication & Role Abuse Focus)¶

📎 Orchestrator JSON Wrapper¶

🧠 Optional Enhancers¶

✅ Summary¶

📤 Output Format and Structure¶

📁 Output Directory Layout¶

📦 Artifact Details¶

🔹 vuln-findings.json (Primary machine-readable output)¶

🔹 vuln-report.md (Human-readable executive summary)¶

🔹 risk-matrix.yaml¶

🔹 poc-artifacts/¶

🔹 trace-log.txt¶

📘 Example Input Snippet: `deployed-endpoints.json`¶

📘 Example Input Snippet: `auth-config.json`¶

📘 Sample: `vuln-findings.json`¶

📘 Sample: `vuln-report.md`¶

📘 Sample: `risk-matrix.yaml`¶

🧠 Skill Example: `OWASPInjectorSkill`¶

🔹 `vuln-findings.json` (Primary machine-readable output)¶

🔹 `vuln-report.md` (Human-readable executive summary)¶

🔹 `risk-matrix.yaml`¶

🔹 `poc-artifacts/`¶

🔹 `trace-log.txt`¶

🔹 `pentest-execution-metadata.json`¶