GuardNest — AI Vulnerability Reporting Engine
A deterministic control plane orchestrating bounded LLM stage-workers to turn raw penetration-test findings into client-ready vulnerability reports — where the model writes prose but is structurally forbidden from inventing or altering a CVE, CVSS score, or severity decision.
What GuardNest does
GuardNest is the AI reporting layer for an automated penetration-testing (PTaaS) platform. It consumes structured scanner findings and produces the narrative vulnerability report a client receives — finding write-ups, remediation guidance, and an executive summary with attack-chain analysis. The engineering thesis is a deliberate inversion of the typical LLM-first design: the language model never holds authority over a security fact. Rules own the facts; the model owns the wording.
Problem & threat model
A vulnerability report is a legal and trust artifact. A fabricated CVE, an inflated CVSS score, or an invented exploit isn't a cosmetic error — it's a client-liability event. Yet the raw material (scanner output) is high-volume and must become fluent prose fast. LLMs solve the prose problem and introduce a new one: hallucination directly on the fields that must never be wrong.
System architecture
The system is a deterministic control plane with bounded LLM autonomy at individual stages. Evidence is frozen before any model runs. The orchestrator schedules stage-workers; the gate is the single authority on whether a report may render.
Who owns what
The trust boundary is the central control. Everything above it is deterministic and authoritative; everything below it is generative and advisory. The model can read facts to describe them, but its output re-enters the system only through the gate.
- ▸CVE identifiers & NVD verification
- ▸CVSS vectors, scores & severity
- ▸Exploit evidence & finding provenance
- ▸Which findings appear in the report
- ▸Finding write-up prose
- ▸Remediation wording
- ▸Executive-summary narrative
- ▸Attack-chain explanation
Pipeline deep-dive
The pipeline is freeze → writer → QA → gate → reviser → render. The gate is a pure function of the frozen snapshot and NVD — no model in the loop — so its verdict is reproducible and auditable.
The frozen snapshot is immutable and append-only; enrichment never overwrites source evidence:
@dataclass(frozen=True)
class FrozenFinding:
finding_id: str
cve_ids: tuple[str, ...] # from scanner, verified vs NVD
cvss_vector: str # authoritative, never model-written
severity: Severity # derived by rule, not prompt
evidence_hash: str # provenance seal
def with_enrichment(self, e: Enrichment) -> "FrozenFinding":
# append-only: returns a new object; source fields are immutable
return replace(self, enrichment=(*self.enrichment, e))The gate re-derives every factual claim and fails closed — any mismatch blocks the render and routes back to a bounded reviser:
def gate(report: DraftReport, snap: FrozenSnapshot) -> GateResult:
for claim in extract_factual_claims(report):
fact = snap.lookup(claim.finding_id)
if claim.cve_ids - set(fact.cve_ids): # model invented a CVE
return GateResult.fail(claim, "unverifiable CVE")
if claim.cvss != fact.cvss_vector: # model altered a score
return GateResult.fail(claim, "CVSS mismatch")
if not nvd.verifies(claim.cve_ids): # not in authoritative source
return GateResult.fail(claim, "NVD unverified")
return GateResult.ok() # only now may the report renderArchitecture decision records
Deterministic spine over agentic autonomy
Context: a fully agentic reporter is flexible but non-deterministic on the exact fields that carry liability.
Decision: a deterministic chained pipeline owns control and facts; agency is bounded to prose generation at individual stages.
Consequence: reproducible, auditable reports; agency added only where its failure mode is acceptable.
Gate as a pure function of frozen evidence + NVD
Decision: the gate takes no model input; it re-derives claims from the immutable snapshot and NVD and fails closed.
Consequence: the correctness guarantee is structural, not probabilistic — the same input always yields the same verdict.
Knowledge layer is advisory, never authoritative
Decision: the governed knowledge layer supplies remediation patterns and methodology, but is scoped so it can never emit a factual security claim that reaches a report unchecked.
Consequence: RAG improves quality without becoming an unaudited fact source — closing OWASP LLM08-style risks.
Security posture · OWASP LLM
Scan findings are untrusted input — they may contain attacker-controlled strings. The architecture treats them as hostile by default.