audit

package
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 3, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const HarnessName = "audit"

HarnessName is the on-disk identifier for the vigolium-audit harness. Drives the env-var prefix, finding-id prefix, and AgenticScan.Mode value. The on-disk output dir (`<source>/vigolium-results/`) and the session subdir (`<session>/vigolium-results/`) are set independently on HarnessSpec to match the upstream binary's output directory name.

Variables

This section is empty.

Functions

func BuildAgenticScan 

func BuildAgenticScan(state *State, folderPath, projectUUID string) *database.AgenticScan

BuildAgenticScan creates a database.AgenticScan from the parsed audit state. Defaults to vigolium-audit metadata; use BuildAgenticScanWithSource to override.

func BuildAgenticScanWithSource 

func BuildAgenticScanWithSource(state *State, folderPath, projectUUID string, src FindingSource) *database.AgenticScan

BuildAgenticScanWithSource is the source-aware variant. The piolium harness uses this so its DB rows tag as "piolium" rather than "audit" while sharing the on-disk schema and parser.

func BuildFindings 

func BuildFindings(findings []*Finding, auditID, agenticScanUUID, projectUUID, repoName string) []*database.Finding

BuildFindings converts parsed Findings to database.Finding structs using vigolium-audit metadata. Callers needing a different source flavor (e.g. piolium) should use BuildFindingsWithSource.

func BuildFindingsWithSource 

func BuildFindingsWithSource(findings []*Finding, auditID, agenticScanUUID, projectUUID, repoName string, src FindingSource) []*database.Finding

BuildFindingsWithSource is the source-aware variant. The piolium harness uses this so module_ids prefix as "piolium:..." and tags include "piolium" rather than "audit".

Types

type Entry 

type Entry struct {
	AuditID          string                `json:"audit_id"`
	Commit           string                `json:"commit"`
	Branch           string                `json:"branch"`
	Repo             string                `json:"repo,omitempty"`       // optional repo slug (e.g. "goharbor/harbor")
	Repository       string                `json:"repository,omitempty"` // alternate key used by lite/balanced modes
	RepoURL          string                `json:"repo_url,omitempty"`   // optional full repo URL
	Mode             string                `json:"mode,omitempty"`       // audit mode: lite, balanced, deep, merge, revisit
	Model            string                `json:"model,omitempty"`      // model used (e.g. opus-4.6, gpt-5.3-codex)
	AgentSDK         string                `json:"agent_sdk,omitempty"`  // platform (e.g. claude-code, codex, bytesec)
	HistoryAvailable *bool                 `json:"history_available,omitempty"`
	StartedAt        flexTime              `json:"started_at"`
	CompletedAt      flexTime              `json:"completed_at"`
	Status           string                `json:"status"`
	Phases           map[string]PhaseEntry `json:"phases"`
}

Entry is a single audit run inside audit-state.json.

func (Entry) EffectiveRepo 

func (e Entry) EffectiveRepo() string

EffectiveRepo returns the repo name from whichever JSON field was populated.

type Finding 

type Finding struct {
	// Common fields
	FindingID  string // e.g. "P7-001", "P8-001"
	Phase      string // "7", "8", "10"
	Sequence   string // "001", "002"
	Slug       string // e.g. "open-redirect-authproxy"
	Title      string
	Severity   string
	Confidence string
	CWE        string
	Verdict    string // VALID, INVALID, etc.
	PoCStatus  string // theoretical, pending, confirmed

	// Phase 8+ specific
	SeverityOriginal     string
	SeverityFinal        string
	AdversarialVerdict   string
	AdversarialRationale string

	// Locations extracted from the body
	Locations []string

	// Full markdown body (everything after frontmatter/header)
	Body string

	// Source filename
	Filename string

	// Enrichment from promoted finding directories
	Remediation     string // extracted from ## Fix / ## Remediation sections
	PoCFile         string // filename of poc.* file (e.g. "poc.py", "poc.sh")
	PoCContent      string // raw content of poc.* file
	IsVariant       bool
	OriginFindingID string // e.g. "H6" when this finding is a variant

	// Provenance marks which directory the finding was read from:
	//   ""            promoted/confirmed (findings/) — keeps its real severity
	//   "theoretical" findings-theoretical/ (VALID but not confirmed)
	//   "draft"       findings-draft/ imported alongside a populated findings/
	// Non-empty values are coerced to INFO severity and tagged at DB-build
	// time so they read as informational context, not confirmed bugs.
	Provenance string
}

Finding is the intermediate representation of a parsed finding file.

type FindingSource 

type FindingSource struct {
	Mode      string // database.AgenticScan.Mode (e.g. "audit", "piolium")
	AgentName string // database.AgenticScan.AgentName (e.g. "vigolium-audit", "piolium")
	InputType string // database.AgenticScan.InputType
	IDPrefix  string // module_id prefix (e.g. "audit" → "audit:c1-...", "piolium" → "piolium:c1-...")
	Tag       string // tag added to every finding (e.g. "audit", "piolium")
}

FindingSource carries the import-source metadata used when converting Findings into database rows. The audit and piolium harnesses share the same on-disk schema but tag their DB rows differently so they can be queried apart. DefaultSource() returns the values used for audit runs; piolium populates its own values via PioliumSource().

func DefaultSource 

func DefaultSource() FindingSource

DefaultSource returns the metadata for vigolium-audit runs. Used by callers that don't explicitly choose a harness flavor.

type Import 

type Import struct {
	RawFindings  []*Finding
	State        *State
	RevisitState *RevisitState // nil when no revisit-audit-state.json exists
	RepoName     string        // resolved repo name (URL preferred, then slug, then folder basename)
}

Import holds the parsed result of an audit output folder.

func ParseFolder 

func ParseFolder(folderPath string) (*Import, error)

ParseFolder parses an audit output folder and returns the import data. It tolerates a missing audit-state.json (e.g. when the audit process was cancelled before completing).

Findings are read from findings/ (promoted, severity-prefixed IDs) when present. In addition, findings-theoretical/ (VALID-but-not-confirmed) and, when findings/ is populated, findings-draft/ (intermediate p/l/q-prefixed drafts) are imported as supplementary findings flagged via Finding.Provenance so they land as INFO-severity informational context. When findings/ is empty (cancelled/partial run) findings-draft/ stands in as the primary set and keeps its real draft severities.

type KnownFinding 

type KnownFinding struct {
	ID       string `json:"id"`
	Slug     string `json:"slug"`
	Class    string `json:"class"`
	Location string `json:"location"`
}

KnownFinding represents a finding from a prior audit round.

type MergeMetadata 

type MergeMetadata struct {
	Sources   []string          `json:"sources,omitempty"`
	RenameMap map[string]string `json:"rename_map,omitempty"`
}

MergeMetadata captures the provenance of a merged audit.

type PhaseEntry 

type PhaseEntry struct {
	Status      string                 `json:"status"`
	CompletedAt flexTime               `json:"completed_at"`
	Summary     map[string]interface{} `json:"-"` // populated by custom unmarshal
	SummaryRaw  json.RawMessage        `json:"summary,omitempty"`
}

PhaseEntry describes one phase in the audit. Summary is flexible: LLM-generated audit-state.json may produce a plain string or a structured object. We accept both and normalise to map[string]interface{}.

func (PhaseEntry) SummaryText 

func (p PhaseEntry) SummaryText() string

SummaryText returns the summary as a plain string if it was provided as one, or empty string otherwise.

func (*PhaseEntry) UnmarshalJSON 

func (p *PhaseEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON implements lenient parsing for PhaseEntry. It accepts summary as a string, an object, or absent.

type RevisitEntry 

type RevisitEntry struct {
	RevisitID     string                `json:"revisit_id"`
	ParentAuditID string                `json:"parent_audit_id"`
	Round         int                   `json:"round"`
	Commit        string                `json:"commit"`
	Branch        string                `json:"branch"`
	Repository    string                `json:"repository,omitempty"`
	Mode          string                `json:"mode,omitempty"`
	Model         string                `json:"model,omitempty"`
	AgentSDK      string                `json:"agent_sdk,omitempty"`
	StartedAt     flexTime              `json:"started_at"`
	CompletedAt   flexTime              `json:"completed_at"`
	Status        string                `json:"status"`
	Phases        map[string]PhaseEntry `json:"phases"`
	Seed          *RevisitSeed          `json:"seed,omitempty"`
	NewFindingIDs []string              `json:"new_finding_ids,omitempty"`
}

RevisitEntry is a single revisit run.

type RevisitSeed 

type RevisitSeed struct {
	KBPath                    string         `json:"kb_path,omitempty"`
	KnownFindings             []KnownFinding `json:"known_findings,omitempty"`
	KnownAttackModes          []string       `json:"known_attack_modes,omitempty"`
	KnownFindingIDsBySeverity map[string]int `json:"known_finding_ids_by_severity,omitempty"`
}

RevisitSeed captures the known findings and attack modes from the prior audit.

type RevisitState 

type RevisitState struct {
	Revisits []RevisitEntry `json:"revisits"`
}

RevisitState represents the top-level revisit-audit-state.json structure.

type State 

type State struct {
	Audits        []Entry        `json:"audits"`
	MergeMetadata *MergeMetadata `json:"merge_metadata,omitempty"`
}

State represents the top-level audit-state.json structure.

Source Files

View all Source files

Directories

Path Synopsis
Package bin embeds the vigolium-audit host binary into vigolium and extracts it to a per-user cache directory on first use.
 Package bin embeds the vigolium-audit host binary into vigolium and extracts it to a per-user cache directory on first use.
Package claudecost computes estimated token usage and USD cost for an vigolium-audit run by parsing the Claude CLI's stream-json transcript.
 Package claudecost computes estimated token usage and USD cost for an vigolium-audit run by parsing the Claude CLI's stream-json transcript.
Package auditstream decodes vigolium-audit's NDJSON output format (emitted when the binary is invoked with `--json`) and renders it as a compact, colored activity feed suitable for a terminal.
 Package auditstream decodes vigolium-audit's NDJSON output format (emitted when the binary is invoked with `--json`) and renders it as a compact, colored activity feed suitable for a terminal.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.