security

Classes

AuditTrail

Defined in: packages/nexus-agents/src/security/audit-trail.ts:247

Constructors

Constructor

new AuditTrail(durableSink?): AuditTrail;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:251

Parameters

durableSink?

DurableAuditSink

Returns

AuditTrail

Accessors

size

Get Signature

get size(): number;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:315

Returns the total number of events.

Returns

number

Methods

append()

append(event): string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:254

Appends an event to the trail. Returns the assigned event ID.

Parameters

event

Omit<SecurityAuditEvent, "id" | "timestamp">

Returns

string

clear()

clear(): void;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:320

Clears all events.

Returns

void

query()

query(filter?): readonly SecurityAuditEvent[];

Defined in: packages/nexus-agents/src/security/audit-trail.ts:279

Queries events matching the given filter.

Parameters

Orchestrates existing security modules into a configurable pipeline. Each stage is independently toggleable via config.stages.

Constructors

Constructor

new HostileInputFirewall(config): HostileInputFirewall;

Defined in: packages/nexus-agents/src/security/firewall/firewall-pipeline.ts:116

Parameters

config

FirewallConfig

Returns

HostileInputFirewall

Methods

evaluateAction()

evaluateAction(action, options): Result<FirewallActionPolicyResult, FirewallError>;

Defined in: packages/nexus-agents/src/security/firewall/firewall-pipeline.ts:225

Action-shaped re-entry that evaluates policy for one action against an already-enforced trust tier (#6310).

Unlike process, this does NOT re-run input extraction, sanitization, trust classification, or reputation gating, and does NOT re-emit the input-level audit events (sanitization, reputation, trust_classification). It evaluates the policy stage against the provided tier and context, recording only the policy_gate event to the audit trail.

Parameters

action

| { sources: ( | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; issueNumber: number; type: "issueBody"; } | { commit?: string; existsOnBaseRef?: boolean; line?: number; path: string; type: "repoFile"; } | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; commentId: number; issueNumber: number; type: "issueComment"; } | { job: string; runId: number; status: "pass" | "fail"; type: "ciResult"; } | { path: string; section: string; type: "policyDoc"; } | { commentId: number; type: "maintainerCommand"; username: string; })[]; summary: string; type: "SummarizeIssue"; } | { labels: string[]; reason: string; sources: ( | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; issueNumber: number; type: "issueBody"; } | { commit?: string; existsOnBaseRef?: boolean; line?: number; path: string; type: "repoFile"; } | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; commentId: number; issueNumber: number; type: "issueComment"; } | { job: string; runId: number; status: "pass" | "fail"; type: "ciResult"; } | { path: string; section: string; type: "policyDoc"; } | { commentId: number; type: "maintainerCommand"; username: string; })[]; type: "ProposeLabels"; } | { body: string; requiresApproval: true; sources: ( | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; issueNumber: number; type: "issueBody"; } | { commit?: string; existsOnBaseRef?: boolean; line?: number; path: string; type: "repoFile"; } | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; commentId: number; issueNumber: number; type: "issueComment"; } | { job: string; runId: number; status: "pass" | "fail"; type: "ciResult"; } | { path: string; section: string; type: "policyDoc"; } | { commentId: number; type: "maintainerCommand"; username: string; })[]; type: "DraftReply"; } | { context: string; reason: string; type: "RequestHumanApproval"; } | { files: { description: string; operation: "create" | "delete" | "modify"; path: string; }[]; rationale: string; requiresApproval: true; sources: ( | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; issueNumber: number; type: "issueBody"; } | { commit?: string; existsOnBaseRef?: boolean; line?: number; path: string; type: "repoFile"; } | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; commentId: number; issueNumber: number; type: "issueComment"; } | { job: string; runId: number; status: "pass" | "fail"; type: "ciResult"; } | { path: string; section: string; type: "policyDoc"; } | { commentId: number; type: "maintainerCommand"; username: string; })[]; type: "GeneratePatchPlan"; } | { category: | "security" | "documentation" | "performance" | "question" | "bug" | "feature"; confidence: number; sources: ( | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; issueNumber: number; type: "issueBody"; } | { commit?: string; existsOnBaseRef?: boolean; line?: number; path: string; type: "repoFile"; } | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; commentId: number; issueNumber: number; type: "issueComment"; } | { job: string; runId: number; status: "pass" | "fail"; type: "ciResult"; } | { path: string; section: string; type: "policyDoc"; } | { commentId: number; type: "maintainerCommand"; username: string; })[]; type: "ClassifyIssue"; } | { candidates: number[]; similarity: number[]; sources: ( | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; issueNumber: number; type: "issueBody"; } | { commit?: string; existsOnBaseRef?: boolean; line?: number; path: string; type: "repoFile"; } | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; commentId: number; issueNumber: number; type: "issueComment"; } | { job: string; runId: number; status: "pass" | "fail"; type: "ciResult"; } | { path: string; section: string; type: "policyDoc"; } | { commentId: number; type: "maintainerCommand"; username: string; })[]; type: "IdentifyDuplicates"; } | { escalateTo: "security" | "maintainer"; reason: string; type: "RefuseAction"; } | { inputTrustTier: "1" | "2" | "3" | "4"; reason: string; sources: ( | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; issueNumber: number; type: "issueBody"; } | { commit?: string; existsOnBaseRef?: boolean; line?: number; path: string; type: "repoFile"; } | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; commentId: number; issueNumber: number; type: "issueComment"; } | { job: string; runId: number; status: "pass" | "fail"; type: "ciResult"; } | { path: string; section: string; type: "policyDoc"; } | { commentId: number; type: "maintainerCommand"; username: string; })[]; targetCapability: string; type: "HandoffMessage"; }

options

FirewallActionEvaluationOptions

Returns

Result<FirewallActionPolicyResult, FirewallError>

getAuditTrail()

getAuditTrail(): AuditTrail;

Defined in: packages/nexus-agents/src/security/firewall/firewall-pipeline.ts:378

Returns the internal audit trail for inspection.

Returns

AuditTrail

process()

process(input, options?): Result<FirewallResult, FirewallError>;

Defined in: packages/nexus-agents/src/security/firewall/firewall-pipeline.ts:159

Processes untrusted input through the firewall pipeline. Returns a structured FirewallResult or a typed FirewallError.

options carries the per-call facts (#4992): the repository’s maintainer allowlist and the caller’s access posture. Each replaces its construction-time counterpart for this call only, so one shared instance never holds a repository’s allowlist or a caller’s posture process-wide.

Parameters

input

unknown

options?

FirewallProcessOptions

Returns

Result<FirewallResult, FirewallError>

validateAction()

validateAction(action): Result<ActionValidation, FirewallError>;

Defined in: packages/nexus-agents/src/security/firewall/firewall-pipeline.ts:340

Validates corroboration for a decided action (#5382).

Separate from process because the two operate at different points in the lifecycle, which is the real shape of the divergence epic #5281 found: process() is INPUT-shaped — it sanitizes, classifies and labels untrusted content — while corroboration is ACTION-shaped, asking whether a decision the consumer has now reached is backed by sources of sufficient tier. There is no AgentAction in scope during process(), so the stages.corroboration flag could never have been wired there; this is the entry point that makes it readable.

It is also the shape #5383 needs: production validates corroboration per action (issue-triage.ts:391), so those callers cannot migrate onto the firewall unless it offers a per-action surface.

Returns evaluated: false when the stage is disabled — never a satisfied verdict for a check that did not run. Under enforce an unsatisfied action is refused with POLICY_REFUSED; under audit the would-be refusal is reported via wouldRefuse and the action is allowed through.

Parameters

action

Returns

Result<ActionValidation, FirewallError>

ReputationCache

Defined in: packages/nexus-agents/src/security/reputation-model.ts:112

In-memory reputation cache with TTL and max size. Reduces redundant assessments for the same user within a short window. Evicts oldest entries when max size is exceeded.

Constructors

Constructor

new ReputationCache(ttlMs?, maxSize?): ReputationCache;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:117

Parameters

ttlMs?

number = DEFAULT_TTL_MS

maxSize?

number = DEFAULT_MAX_SIZE

Returns

ReputationCache

Accessors

size

Get Signature

get size(): number;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:157

Returns

number

Methods

clear()

clear(): void;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:153

Returns

void

get()

get(username): ReputationAssessment | undefined;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:122

Parameters

username

string

Returns

ReputationAssessment | undefined

set()

set(username, assessment): void;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:132

Parameters

username

string

assessment

ReputationAssessment

Returns

void

Interfaces

ActionContext

Defined in: packages/nexus-agents/src/security/policy-gate.ts:63

Context for evaluating a policy decision.

Properties

existingLabels?

readonly optional existingLabels?: ReadonlySet<string>;

Defined in: packages/nexus-agents/src/security/policy-gate.ts:71

Set of labels that exist on the repository (for ProposeLabels validation).

hasSecretAccess

readonly hasSecretAccess: boolean;

Defined in: packages/nexus-agents/src/security/policy-gate.ts:69

Whether the agent currently has access to secrets/tokens.

hasWriteAccess

readonly hasWriteAccess: boolean;

Defined in: packages/nexus-agents/src/security/policy-gate.ts:67

Whether the agent currently has write access to the repository.

inputTrustTier

readonly inputTrustTier: "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/policy-gate.ts:65

Trust tier of the primary input source.

AstQaCollectResult

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:307

collectAstQaFindings’s full result — findings plus the true total, so overflow beyond limit is counted and reported, never silently dropped.

Properties

filesScanned

filesScanned: number;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:313

Number of .py/.go files actually scanned (after the file cap).

filesSkipped

filesSkipped: number;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:317

Number of discovered files DROPPED because the file cap (MAX_FILES_SCANNED) was exceeded. Non-zero means the scan was PARTIAL — a downstream consumer must not treat empty/low findings as a clean bill of health.

filesTruncated

filesTruncated: boolean;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:319

True iff filesSkipped > 0 — the scan did not cover every candidate file.

findings

findings: AstRuleFinding[];

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:308

limit

limit: number;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:311

total

total: number;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:310

True count of matches found, before the limit cap was applied.

AstRuleFinding

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:282

One ast-grep rule match against a source file.

Properties

column

column: number;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:291

1-based column number.

file

file: string;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:287

Path relative to the resolved targetDir.

line

line: number;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:289

1-based line number.

message

message: string;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:285

ruleId

ruleId: string;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:283

severity

severity: "error" | "info" | "warning";

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:284

snippet

snippet: string;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:293

Trimmed, length-capped source line for the match.

ClassifyInput

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:52

Input for trust classification.

Properties

authorAssociation

readonly authorAssociation: string;

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:56

GitHub API author_association value.

config?

readonly optional config?: Partial<{
  allowlistedMaintainers: string[];
  failOpen: boolean;
  maxInputLength: number;
}>;

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:60

Sanitizer config (for allowlist check).

sanitizedInput?

readonly optional sanitizedInput?: {
  content: string;
  contentTierMeasured?: boolean;
  injectionFlags: (
     | "authority_claim"
     | "instruction_pattern"
     | "system_prompt_manipulation"
     | "hidden_content"
     | "urgency_manipulation"
     | "fake_conversation"
     | "base64_encoded"
    | "external_link_instruction")[];
  originalLength: number;
  sanitizationIncomplete?: boolean;
  sanitizedAt: string;
  strippedElements: {
     length: number;
     reason: string;
     startIndex: number;
     tag: string;
  }[];
  truncated?: boolean;
  trustTier: "1" | "2" | "3" | "4";
  userRole:   | "unknown"
     | "owner"
     | "maintainer"
     | "collaborator"
     | "contributor"
     | "member";
  wasModified: boolean;
};

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:58

Sanitized input (if content has already been through the sanitizer).

content

content: string;

Sanitized content with dangerous elements removed.

contentTierMeasured?

optional contentTierMeasured?: boolean;

True when trustTier is the sanitizer’s measured content tier; false when the sanitization stage was disabled and trustTier is only the role-derived base tier. Absent on records that predate this field; an absent value MUST be treated as measured so legacy content downgrades are preserved fail-closed.

injectionFlags

injectionFlags: (
  | "authority_claim"
  | "instruction_pattern"
  | "system_prompt_manipulation"
  | "hidden_content"
  | "urgency_manipulation"
  | "fake_conversation"
  | "base64_encoded"
  | "external_link_instruction")[];

Injection patterns detected in content.

originalLength

originalLength: number;

Original content before sanitization (for audit).

sanitizationIncomplete?

optional sanitizationIncomplete?: boolean;

True when a strip loop exhausted its pass budget with its own pattern still matching — i.e. content still carries markup the sanitizer removes.

Absent on records that predate this field, and absent means converged, so no existing record changes meaning. Treat true as “do not hand this to a model”: wasModified is true and strippedElements.length is at the cap in BOTH the converged and the unconverged case, so nothing else separated them. Mirrors sanitizationIncomplete on the MCP-layer sanitizer (#5788).

sanitizedAt

sanitizedAt: string;

Timestamp of sanitization (ISO 8601).

strippedElements

strippedElements: {
  length: number;
  reason: string;
  startIndex: number;
  tag: string;
}[];

Elements stripped during sanitization (audit trail).

truncated?

optional truncated?: boolean;

Whether content exceeded the configured limit. Absent on records that predate this field.

trustTier

trustTier: "1" | "2" | "3" | "4" = TrustTierSchema;

Assigned trust tier based on user role and content analysis.

Deprecation note: required today; a future major makes it absent when unmeasured (see the next-major issue named in the changeset).

userRole

userRole: 
  | "unknown"
  | "owner"
  | "maintainer"
  | "collaborator"
  | "contributor"
  | "member" = GitHubUserRoleSchema;

GitHub user role of the input source.

wasModified

wasModified: boolean;

Whether any dangerous content was detected and stripped.

username

readonly username: string;

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:54

GitHub username.

ClassifyResult

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:66

Result of trust classification.

Properties

isAllowlisted

readonly isAllowlisted: boolean;

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:72

Whether the user is on the maintainer allowlist.

reason

readonly reason: string;

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:76

Reason for the assigned tier.

trustTier

readonly trustTier: "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:68

Assigned trust tier.

userRole

readonly userRole: 
  | "unknown"
  | "owner"
  | "maintainer"
  | "collaborator"
  | "contributor"
  | "member";

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:70

GitHub user role.

wasDowngraded

readonly wasDowngraded: boolean;

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:74

Whether content triggered a trust downgrade.

CorroborationEvent

Defined in: packages/nexus-agents/src/security/audit-trail.ts:113

Corroboration validation result.

Extends

AuditEventBase

Properties

actionType

readonly actionType: 
  | "GeneratePatchPlan"
  | "DraftReply"
  | "ProposeLabels"
  | "SummarizeIssue"
  | "ClassifyIssue"
  | "IdentifyDuplicates"
  | "RequestHumanApproval"
  | "RefuseAction"
  | "HandoffMessage";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:115

component

readonly component: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:44

Inherited from

AuditEventBase.component

id

readonly id: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:42

Inherited from

AuditEventBase.id

missingRequirements

readonly missingRequirements: readonly string[];

Defined in: packages/nexus-agents/src/security/audit-trail.ts:118

satisfied

readonly satisfied: boolean;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:116

sourceCount

readonly sourceCount: number;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:117

timestamp

readonly timestamp: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:43

Inherited from

AuditEventBase.timestamp

type

readonly type: "corroboration";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:114

CorroborationResult

Defined in: packages/nexus-agents/src/security/corroboration-validator.ts:26

Result of corroboration validation.

Properties

actionType

readonly actionType: 
  | "GeneratePatchPlan"
  | "DraftReply"
  | "ProposeLabels"
  | "SummarizeIssue"
  | "ClassifyIssue"
  | "IdentifyDuplicates"
  | "RequestHumanApproval"
  | "RefuseAction"
  | "HandoffMessage";

Defined in: packages/nexus-agents/src/security/corroboration-validator.ts:34

Action type that was validated.

clearedOnlyByUnverifiedSources

readonly clearedOnlyByUnverifiedSources: boolean;

Defined in: packages/nexus-agents/src/security/corroboration-validator.ts:47

True when the floor was cleared, and EVERY repoFile citation that cleared it is one the producer checked and found absent from the base ref (existsOnBaseRef === false) — i.e. a path the author of the untrusted change invented in that same change.

satisfied deliberately does not read this: which actions are permitted is unchanged. What changes is that the record can now say the corroboration was author-supplied, instead of attributing repo provenance to a path that has none. False when any citation is verified, when none were checked, or when the floor was not cleared at all.

corroboratingSources

readonly corroboratingSources: readonly (
  | {
  author: string;
  authorTrustTier: "1" | "2" | "3" | "4";
  issueNumber: number;
  type: "issueBody";
}
  | {
  commit?: string;
  existsOnBaseRef?: boolean;
  line?: number;
  path: string;
  type: "repoFile";
}
  | {
  author: string;
  authorTrustTier: "1" | "2" | "3" | "4";
  commentId: number;
  issueNumber: number;
  type: "issueComment";
}
  | {
  job: string;
  runId: number;
  status: "pass" | "fail";
  type: "ciResult";
}
  | {
  path: string;
  section: string;
  type: "policyDoc";
}
  | {
  commentId: number;
  type: "maintainerCommand";
  username: string;
})[];

Defined in: packages/nexus-agents/src/security/corroboration-validator.ts:30

Sources that contributed to corroboration.

missing

readonly missing: readonly string[];

Defined in: packages/nexus-agents/src/security/corroboration-validator.ts:32

Missing corroboration requirements (empty when satisfied).

satisfied

readonly satisfied: boolean;

Defined in: packages/nexus-agents/src/security/corroboration-validator.ts:28

Whether corroboration requirements are satisfied.

CorroborationRule

Defined in: packages/nexus-agents/src/security/corroboration-validator.ts:53

Rule defining what corroboration an action requires.

Properties

description

readonly description: string;

Defined in: packages/nexus-agents/src/security/corroboration-validator.ts:55

Human-readable description of what’s required.

isSatisfied

readonly isSatisfied: (sources) => boolean;

Defined in: packages/nexus-agents/src/security/corroboration-validator.ts:57

Predicate: does this set of sources satisfy the requirement?

Parameters

sources

readonly ( | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; issueNumber: number; type: "issueBody"; } | { commit?: string; existsOnBaseRef?: boolean; line?: number; path: string; type: "repoFile"; } | { author: string; authorTrustTier: "1" | "2" | "3" | "4"; commentId: number; issueNumber: number; type: "issueComment"; } | { job: string; runId: number; status: "pass" | "fail"; type: "ciResult"; } | { path: string; section: string; type: "policyDoc"; } | { commentId: number; type: "maintainerCommand"; username: string; })[]

Returns

boolean

EvaluationCriterion

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:67

Definition of an evaluation criterion for safety assessment.

Properties

categories?

readonly optional categories?: readonly string[];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:81

Categories for categorical type.

description

readonly description: string;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:73

Detailed description of what the criterion measures.

id

readonly id: string;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:69

Unique criterion identifier.

name

readonly name: string;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:71

Human-readable criterion name.

passThreshold?

readonly optional passThreshold?: number;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:79

Threshold value for pass (for threshold type).

type

readonly type: CriterionTypeType;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:75

Type of evaluation (binary, scaled, threshold, categorical).

weight

readonly weight: number;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:77

Weight factor for scoring (0.0-1.0).

FirewallActionEvaluationOptions

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-stage.ts:197

Options for action-level policy evaluation (#6310).

Properties

context?

readonly optional context?: {
  hasSecretAccess: boolean;
  hasWriteAccess: boolean;
};

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-stage.ts:203

Access posture for the evaluation. Defaults to firewall context.

hasSecretAccess

readonly hasSecretAccess: boolean;

hasWriteAccess

readonly hasWriteAccess: boolean;

effectiveTrustTier

readonly effectiveTrustTier: "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-stage.ts:201

The enforced trust tier from the classification run.

existingLabels?

readonly optional existingLabels?: ReadonlySet<string>;

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-stage.ts:206

Known repository labels for label validity checks.

user

readonly user: string;

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-stage.ts:199

The author/username of the input.

FirewallProcessOptions

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:187

Per-call inputs to HostileInputFirewall.process (#4992).

These are the facts that vary by CALL rather than by instance, so a process-wide firewall (the dogfooding singleton) can serve many repositories and many access postures without holding any of them globally.

Properties

action?

readonly optional action?: 
  | {
  sources: (
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     issueNumber: number;
     type: "issueBody";
   }
     | {
     commit?: string;
     existsOnBaseRef?: boolean;
     line?: number;
     path: string;
     type: "repoFile";
   }
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     commentId: number;
     issueNumber: number;
     type: "issueComment";
   }
     | {
     job: string;
     runId: number;
     status: "pass" | "fail";
     type: "ciResult";
   }
     | {
     path: string;
     section: string;
     type: "policyDoc";
   }
     | {
     commentId: number;
     type: "maintainerCommand";
     username: string;
  })[];
  summary: string;
  type: "SummarizeIssue";
}
  | {
  labels: string[];
  reason: string;
  sources: (
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     issueNumber: number;
     type: "issueBody";
   }
     | {
     commit?: string;
     existsOnBaseRef?: boolean;
     line?: number;
     path: string;
     type: "repoFile";
   }
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     commentId: number;
     issueNumber: number;
     type: "issueComment";
   }
     | {
     job: string;
     runId: number;
     status: "pass" | "fail";
     type: "ciResult";
   }
     | {
     path: string;
     section: string;
     type: "policyDoc";
   }
     | {
     commentId: number;
     type: "maintainerCommand";
     username: string;
  })[];
  type: "ProposeLabels";
}
  | {
  body: string;
  requiresApproval: true;
  sources: (
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     issueNumber: number;
     type: "issueBody";
   }
     | {
     commit?: string;
     existsOnBaseRef?: boolean;
     line?: number;
     path: string;
     type: "repoFile";
   }
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     commentId: number;
     issueNumber: number;
     type: "issueComment";
   }
     | {
     job: string;
     runId: number;
     status: "pass" | "fail";
     type: "ciResult";
   }
     | {
     path: string;
     section: string;
     type: "policyDoc";
   }
     | {
     commentId: number;
     type: "maintainerCommand";
     username: string;
  })[];
  type: "DraftReply";
}
  | {
  context: string;
  reason: string;
  type: "RequestHumanApproval";
}
  | {
  files: {
     description: string;
     operation: "create" | "delete" | "modify";
     path: string;
  }[];
  rationale: string;
  requiresApproval: true;
  sources: (
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     issueNumber: number;
     type: "issueBody";
   }
     | {
     commit?: string;
     existsOnBaseRef?: boolean;
     line?: number;
     path: string;
     type: "repoFile";
   }
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     commentId: number;
     issueNumber: number;
     type: "issueComment";
   }
     | {
     job: string;
     runId: number;
     status: "pass" | "fail";
     type: "ciResult";
   }
     | {
     path: string;
     section: string;
     type: "policyDoc";
   }
     | {
     commentId: number;
     type: "maintainerCommand";
     username: string;
  })[];
  type: "GeneratePatchPlan";
}
  | {
  category:   | "security"
     | "documentation"
     | "performance"
     | "question"
     | "bug"
     | "feature";
  confidence: number;
  sources: (
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     issueNumber: number;
     type: "issueBody";
   }
     | {
     commit?: string;
     existsOnBaseRef?: boolean;
     line?: number;
     path: string;
     type: "repoFile";
   }
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     commentId: number;
     issueNumber: number;
     type: "issueComment";
   }
     | {
     job: string;
     runId: number;
     status: "pass" | "fail";
     type: "ciResult";
   }
     | {
     path: string;
     section: string;
     type: "policyDoc";
   }
     | {
     commentId: number;
     type: "maintainerCommand";
     username: string;
  })[];
  type: "ClassifyIssue";
}
  | {
  candidates: number[];
  similarity: number[];
  sources: (
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     issueNumber: number;
     type: "issueBody";
   }
     | {
     commit?: string;
     existsOnBaseRef?: boolean;
     line?: number;
     path: string;
     type: "repoFile";
   }
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     commentId: number;
     issueNumber: number;
     type: "issueComment";
   }
     | {
     job: string;
     runId: number;
     status: "pass" | "fail";
     type: "ciResult";
   }
     | {
     path: string;
     section: string;
     type: "policyDoc";
   }
     | {
     commentId: number;
     type: "maintainerCommand";
     username: string;
  })[];
  type: "IdentifyDuplicates";
}
  | {
  escalateTo: "security" | "maintainer";
  reason: string;
  type: "RefuseAction";
}
  | {
  inputTrustTier: "1" | "2" | "3" | "4";
  reason: string;
  sources: (
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     issueNumber: number;
     type: "issueBody";
   }
     | {
     commit?: string;
     existsOnBaseRef?: boolean;
     line?: number;
     path: string;
     type: "repoFile";
   }
     | {
     author: string;
     authorTrustTier: "1" | "2" | "3" | "4";
     commentId: number;
     issueNumber: number;
     type: "issueComment";
   }
     | {
     job: string;
     runId: number;
     status: "pass" | "fail";
     type: "ciResult";
   }
     | {
     path: string;
     section: string;
     type: "policyDoc";
   }
     | {
     commentId: number;
     type: "maintainerCommand";
     username: string;
  })[];
  targetCapability: string;
  type: "HandoffMessage";
};

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:233

The action the caller intends to take on this input, for THIS call (#5380).

With it, the policyEnforcement stage runs the full evaluatePolicy set — the same seven checks production runs — against the enforced tier and the call’s access posture, and FirewallResult.policy carries every violation plus the decision’s own requiresApproval. Without it only the Rule of Two, the one context-only check, can run; the six action-scoped checks are then listed under policy.unmeasured rather than silently counted as passed. process() is input-shaped and constructs no action itself, so this is the only way those checks reach it.

allowlistedMaintainers?

readonly optional allowlistedMaintainers?: readonly string[];

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:194

Maintainer allowlist for THIS call, from the repository context. Replaces — does not merge with — the construction-time list, and is forgotten after the call. When neither this nor the construction-time list was supplied, no allowlist is consulted and FirewallResult.isAllowlisted is absent.

context?

readonly optional context?: {
  hasSecretAccess: boolean;
  hasWriteAccess: boolean;
};

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:201

Access posture of the caller for THIS call, feeding the Rule-of-Two check. Replaces the construction-time context for the call. Without it a shared instance would evaluate every caller against one posture, and wouldRefuse could never fire for a caller whose posture differs.

hasSecretAccess

readonly hasSecretAccess: boolean;

hasWriteAccess

readonly hasWriteAccess: boolean;

existingLabels?

readonly optional existingLabels?: ReadonlySet<string>;

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:240

The repository’s label set, consulted by the label-validity check when action is a ProposeLabels (#5380). When absent, evaluatePolicy reports LABEL_SET_UNAVAILABLE as a blocking violation — unevaluable label validity fails closed, exactly as it does on the production path.

reputation?

readonly optional reputation?: {
  assessment: ReputationAssessment | undefined;
};

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:218

The caller’s own reputation measurement for THIS call. When present, the reputation gate runs on it under NEXUS_REPUTATION_GATING, whether or not the instance’s reputationAssessment stage is on: effectiveTrustTier is the enforced tier, reputationGate is returned, and the Rule-of-Two check, wouldRefuse and the trust audit event all use that tier. This is what lets a caller with richer signals than the firewall can see (account age, comment history) act on ONE gate rather than two that can disagree.

assessment: undefined means the caller measured nothing (reputation disabled) but still wants the gate decision recorded on the classifier tier; omitting the option entirely leaves the stage to the instance config.

assessment

readonly assessment: ReputationAssessment | undefined;

FirewallResult

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:311

Output of the firewall pipeline. Aggregates results from each stage.

Properties

atl

readonly atl: string;

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:342

auditEvents

readonly auditEvents: readonly {
  id: string;
  type: string;
}[];

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:379

auditSink

readonly auditSink: "none" | "configured";

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:389

Whether a durable AuditLogger was configured for this instance (#4992 review). configured means this run’s events were HANDED to that logger; delivery to the hash chain is subject to the logger’s own severity filter (trust events are info), its bounded queue and its timed, fail-loud flush, and is NOT confirmed per call — the write is queued. none means the events exist only in the in-memory trail, which the next process() call clears. This is a construction-time fact, not a per-call outcome.

durationMs

readonly durationMs: number;

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:390

effectiveTrustTier

readonly effectiveTrustTier: "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:331

The tier consumers should ENFORCE on (#3106): the classifier tier reconciled with the reputation assessment (demotion-only; Tier-1/allowlist wins; equals trust.trustTier when reputation is absent). Previously the reputation tier was computed but dropped — trust.trustTier alone left reputation unenforced.

evaluateAction

readonly evaluateAction: (action, options?) => Result<FirewallActionPolicyResult, FirewallError>;

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:397

Action-shaped re-entry handle (#6310). Evaluates policy for one action against this classified input’s metadata and enforced tier, recording only the policy_gate event to the audit trail without re-running sanitization, classification or reputation gating.

Parameters

action

options?

Pick<FirewallActionEvaluationOptions, "context" | "existingLabels">

Returns

Result<FirewallActionPolicyResult, FirewallError>

isAllowlisted?

readonly optional isAllowlisted?: boolean;

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:322

Whether the author is on the maintainer allowlist — present ONLY when an allowlist was consulted (#4992), i.e. one was supplied at construction or per call. trust.isAllowlisted is the classifier’s published always-boolean field and reads false whether the list was empty or never supplied; this field is the one to record, because absence here means “not measured” rather than “measured false” — the same treatment reputationGate gets.

policy?

readonly optional policy?: FirewallPolicyEvaluation;

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:358

The policyEnforcement stage’s full verdict (#5380). Absent means the stage did not run. Its scope says how much of evaluatePolicy could be evaluated (FirewallPolicyEvaluation), so “seven checks, none fired” is distinguishable from “one check, six unmeasured”. wouldRefuse and the enforce refusal both derive from policy.violations, whichever scope.

policyMode

readonly policyMode: "audit" | "off" | "enforce";

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:365

The rollout mode this run was evaluated under (#5382). Recorded on the result rather than left implicit so a consumer reading a verdict can tell WHICH policy produced it — a result that does not say which rules were in force cannot be audited later.

reputation?

readonly optional reputation?: ReputationAssessment;

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:323

reputationGate?

readonly optional reputationGate?: ReputationGateDecision;

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:341

The reputation gating decision behind effectiveTrustTier (#5381).

Absent means the reputation stage did not run — not “it ran and suppressed nothing”. ReputationGateDecision.demotionSuppressed is a required boolean, so surfacing it unconditionally would report false for a check that never happened. Since the stage defaults to off, that unevaluated case is the common one.

ruleOfTwoViolation?

readonly optional ruleOfTwoViolation?: {
  message: string;
  rule: string;
  severity: "warn" | "block";
};

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:350

Rule-of-Two assessment surfaced by the policyEnforcement stage (#3198): present (severity: 'block') when the effective tier is untrusted AND the context has both write and secret access; undefined when the stage is disabled or the rule holds. Since #5380 a view onto policy — its RULE_OF_TWO entry — kept so existing consumers read the same field.

message

message: string;

Human-readable description of the violation.

rule

rule: string;

Machine-readable rule identifier.

severity

severity: "warn" | "block";

Severity: ‘block’ prevents execution, ‘warn’ logs only.

sanitized

readonly sanitized: {
  content: string;
  contentTierMeasured?: boolean;
  injectionFlags: (
     | "authority_claim"
     | "instruction_pattern"
     | "system_prompt_manipulation"
     | "hidden_content"
     | "urgency_manipulation"
     | "fake_conversation"
     | "base64_encoded"
    | "external_link_instruction")[];
  originalLength: number;
  sanitizationIncomplete?: boolean;
  sanitizedAt: string;
  strippedElements: {
     length: number;
     reason: string;
     startIndex: number;
     tag: string;
  }[];
  truncated?: boolean;
  trustTier: "1" | "2" | "3" | "4";
  userRole:   | "unknown"
     | "owner"
     | "maintainer"
     | "collaborator"
     | "contributor"
     | "member";
  wasModified: boolean;
};

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:312

content

content: string;

Sanitized content with dangerous elements removed.

contentTierMeasured?

optional contentTierMeasured?: boolean;

injectionFlags

injectionFlags: (
  | "authority_claim"
  | "instruction_pattern"
  | "system_prompt_manipulation"
  | "hidden_content"
  | "urgency_manipulation"
  | "fake_conversation"
  | "base64_encoded"
  | "external_link_instruction")[];

Injection patterns detected in content.

originalLength

originalLength: number;

Original content before sanitization (for audit).

sanitizationIncomplete?

optional sanitizationIncomplete?: boolean;

True when a strip loop exhausted its pass budget with its own pattern still matching — i.e. content still carries markup the sanitizer removes.

sanitizedAt

sanitizedAt: string;

Timestamp of sanitization (ISO 8601).

strippedElements

strippedElements: {
  length: number;
  reason: string;
  startIndex: number;
  tag: string;
}[];

Elements stripped during sanitization (audit trail).

truncated?

optional truncated?: boolean;

Whether content exceeded the configured limit. Absent on records that predate this field.

trustTier

trustTier: "1" | "2" | "3" | "4" = TrustTierSchema;

Assigned trust tier based on user role and content analysis.

Deprecation note: required today; a future major makes it absent when unmeasured (see the next-major issue named in the changeset).

userRole

userRole: 
  | "unknown"
  | "owner"
  | "maintainer"
  | "collaborator"
  | "contributor"
  | "member" = GitHubUserRoleSchema;

GitHub user role of the input source.

wasModified

wasModified: boolean;

Whether any dangerous content was detected and stripped.

trust

readonly trust: ClassifyResult;

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:313

wouldRefuse

readonly wouldRefuse: boolean;

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:378

Whether enforce would have refused this input.

This is what makes audit mode measurable, and it is the field that makes the mode a real gate rather than a switch with two indistinguishable settings: under audit the answer is computed and reported while the input is still allowed through, so an operator can size the impact of flipping to enforce before flipping it.

Always false under enforce, because an input that would be refused IS refused — it comes back as a POLICY_REFUSED error, not a result.

GitHubUserMetadata

Defined in: packages/nexus-agents/src/security/reputation-model.ts:38

GitHub user metadata for reputation assessment.

Properties

accountAgeDays?

readonly optional accountAgeDays?: number;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:47

Account/activity fields are OPTIONAL (#3106). When a field is absent (the caller couldn’t fetch it — e.g. the firewall before Phase 3 wiring), its signal is SKIPPED rather than fabricated: an unknown value must never be treated as benign (the old hardcoded 365/0) nor as hostile. Only the authorAssociation + injectionFlags signals fire on absent activity data.

authorAssociation

readonly authorAssociation: string;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:51

injectionFlags

readonly injectionFlags: readonly (
  | "authority_claim"
  | "instruction_pattern"
  | "system_prompt_manipulation"
  | "hidden_content"
  | "urgency_manipulation"
  | "fake_conversation"
  | "base64_encoded"
  | "external_link_instruction")[];

Defined in: packages/nexus-agents/src/security/reputation-model.ts:52

priorContributions?

readonly optional priorContributions?: number;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:48

recentCommentCount?

readonly optional recentCommentCount?: number;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:49

recentCommentWindowMinutes?

readonly optional recentCommentWindowMinutes?: number;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:50

username

readonly username: string;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:39

GraphExecutionAuditEvent

Defined in: packages/nexus-agents/src/security/audit-trail.ts:197

Graph execution lifecycle event (Issue #839).

Extends

AuditEventBase

Properties

component

readonly component: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:44

Inherited from

AuditEventBase.component

detail

readonly detail: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:202

graphEvent

readonly graphEvent: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:199

id

readonly id: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:42

Inherited from

AuditEventBase.id

nodeId?

readonly optional nodeId?: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:200

stepNumber

readonly stepNumber: number;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:201

timestamp

readonly timestamp: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:43

Inherited from

AuditEventBase.timestamp

type

readonly type: "graph_execution";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:198

ISandboxExecutor

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:166

Interface for sandbox executors.

Properties

name

readonly name: string;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:168

Executor name for logging.

Methods

execute()

execute(
   command, 
   args, 
   options
): Promise<SandboxResult>;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:170

Execute a command in the sandbox.

Parameters

command

string

args

readonly string[]

options

SandboxExecutionOptions

Returns

Promise<SandboxResult>

validate()

validate(
   command, 
   args, 
   options
): PolicyEvaluation;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:176

Validate a command without executing.

Parameters

command

string

args

readonly string[]

options

SandboxExecutionOptions

Returns

PolicyEvaluation

PathAccessRule

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:65

Path access rule for filesystem sandboxing.

Properties

access

readonly access: "none" | "write" | "read";

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:69

Access mode: ‘read’ | ‘write’ | ‘none’.

path

readonly path: string;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:67

Path pattern (supports glob).

PolicyEvaluation

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:97

Result of sandbox policy evaluation.

Properties

allowed

readonly allowed: boolean;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:99

Whether the operation is allowed.

configurationWarnings?

readonly optional configurationWarnings?: readonly string[];

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:112

Configuration mismatches the executor surfaces to operators — capabilities declared in the policy but unenforceable because the corresponding allowlist is empty (e.g. process_spawn set but allowedCommands: []). Source: #2428 ask 1. Not security violations; informational only.

policyId

readonly policyId: string;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:103

Policy that was applied.

reason?

readonly optional reason?: string;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:101

Denial reason if not allowed.

violations

readonly violations: readonly PolicyViolation[];

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:105

Violations found.

PolicyGateEvent

Defined in: packages/nexus-agents/src/security/audit-trail.ts:65

Policy gate evaluation result.

Extends

AuditEventBase

Properties

actionType?

readonly optional actionType?: 
  | "GeneratePatchPlan"
  | "DraftReply"
  | "ProposeLabels"
  | "SummarizeIssue"
  | "ClassifyIssue"
  | "IdentifyDuplicates"
  | "RequestHumanApproval"
  | "RefuseAction"
  | "HandoffMessage";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:74

The agent action evaluated, for the security policy-gate path (security/policy-gate.ts). Optional because the PIPELINE policy path (pipeline/policy-evaluator.ts → #3710) records stage-boundary policy decisions that have no AgentAction — they carry stageType + mode + ruleIds instead. Security emitters always set it.

allowed

readonly allowed: boolean;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:75

component

readonly component: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:44

Inherited from

AuditEventBase.component

id

readonly id: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:42

Inherited from

AuditEventBase.id

inputTrustTier

readonly inputTrustTier: "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:77

mode?

readonly optional mode?: "warn" | "off" | "block";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:87

Enforcement mode the decision was made under: warn (soak) or block (enforce).

recordKind?

readonly optional recordKind?: "summary" | "violation";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:100

#3727: discriminates a per-EVALUATION SUMMARY record ('summary' — emitted once per pipeline policy evaluation INCLUDING clean ones, the DENOMINATOR for the would-block rate) from a per-VIOLATION record ('violation' — the existing #3710 per-violation records). Absent for the security policy-gate path. Denominator = count(recordKind===‘summary’); numerator = summaries with violationCount > 0. Scope the #3710 count-parity assertion to 'violation'.

requiresApproval

readonly requiresApproval: boolean;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:76

ruleIds?

readonly optional ruleIds?: readonly string[];

Defined in: packages/nexus-agents/src/security/audit-trail.ts:89

IDs of the policy rules that fired (mirrors violationRules for the pipeline path).

stageType?

readonly optional stageType?: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:91

Type of the stage the gate guarded (e.g. execute).

timestamp

readonly timestamp: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:43

Inherited from

AuditEventBase.timestamp

trustProvenance?

readonly optional trustProvenance?: ContentTrustProvenance;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:109

#6795: how the gate’s content tier was reached — measured caller tier, declared source tier, whether the declaration was clamped, and the measured source tiers. Set by the dev-pipeline consensus→execute gate; absent on every other path.

type

readonly type: "policy_gate";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:66

violationCount?

readonly optional violationCount?: number;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:102

#3727: number of violations in THIS evaluation (set on the summary record).

violationRules

readonly violationRules: readonly string[];

Defined in: packages/nexus-agents/src/security/audit-trail.ts:78

PolicyViolation

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:118

A specific policy violation.

Properties

denied

readonly denied: string;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:122

What was denied.

reason

readonly reason: string;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:124

Explanation.

type

readonly type: "resource" | "path" | "env" | "capability" | "command";

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:120

Type of violation.

ReputationAssessment

Defined in: packages/nexus-agents/src/security/reputation-model.ts:58

Result of a reputation assessment.

Properties

assessedAt

readonly assessedAt: string;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:70

coverage?

readonly optional coverage?: {
  activity: "unmeasured" | "measured";
};

Defined in: packages/nexus-agents/src/security/reputation-model.ts:62

Measurement coverage; absent on assessments created before coverage tracking.

activity

readonly activity: "unmeasured" | "measured";

effectiveTrustTier

readonly effectiveTrustTier: "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/reputation-model.ts:67

isSuspicious

readonly isSuspicious: boolean;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:66

reason

readonly reason: string;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:69

reputationScore

readonly reputationScore: number;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:68

suspiciousSignals

readonly suspiciousSignals: readonly (
  | "new_account"
  | "no_prior_contributions"
  | "injection_patterns_detected"
  | "rapid_comments"
  | "mismatched_authority_claim")[];

Defined in: packages/nexus-agents/src/security/reputation-model.ts:65

username

readonly username: string;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:59

userRole

readonly userRole: 
  | "unknown"
  | "owner"
  | "maintainer"
  | "collaborator"
  | "contributor"
  | "member";

Defined in: packages/nexus-agents/src/security/reputation-model.ts:60

ReputationEvent

Defined in: packages/nexus-agents/src/security/audit-trail.ts:122

Reputation assessment result.

Extends

AuditEventBase

Properties

component

readonly component: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:44

Inherited from

AuditEventBase.component

effectiveTier

readonly effectiveTier: "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:127

id

readonly id: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:42

Inherited from

AuditEventBase.id

isSuspicious

readonly isSuspicious: boolean;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:126

reputationScore

readonly reputationScore: number;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:125

signalCount

readonly signalCount: number;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:128

timestamp

readonly timestamp: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:43

Inherited from

AuditEventBase.timestamp

type

readonly type: "reputation";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:123

username

readonly username: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:124

ReputationGateDecision

Defined in: packages/nexus-agents/src/security/reputation-model.ts:442

Outcome of applying the gating mode to a reputation assessment.

Properties

demotionSuppressed

readonly demotionSuppressed: boolean;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:448

True when reputation would demote but the mode (off/audit) did not enforce it.

enforcedTier

readonly enforcedTier: "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/reputation-model.ts:444

Tier to actually enforce at the policy gate.

mode

readonly mode: "audit" | "off" | "enforce";

Defined in: packages/nexus-agents/src/security/reputation-model.ts:449

reconciledTier

readonly reconciledTier: "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/reputation-model.ts:446

Tier reputation reconciliation computed (what enforce mode WOULD use).

ResourceLimits

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:38

Resource limits for sandboxed execution.

Properties

maxCpuTimeMs?

readonly optional maxCpuTimeMs?: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:42

Maximum CPU time in milliseconds.

maxMemoryBytes?

readonly optional maxMemoryBytes?: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:40

Maximum memory in bytes (default: 512MB).

maxOutputBytes?

readonly optional maxOutputBytes?: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:46

Maximum output buffer size in bytes.

maxProcesses?

readonly optional maxProcesses?: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:44

Maximum number of child processes.

maxWallTimeMs?

readonly optional maxWallTimeMs?: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:48

Maximum execution time in milliseconds.

ResourceUsage

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:150

Resource usage metrics from sandboxed execution.

Properties

cpuTimeMs

readonly cpuTimeMs: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:154

CPU time used in milliseconds.

memoryBytes

readonly memoryBytes: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:152

Memory used in bytes.

outputBytes

readonly outputBytes: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:158

Output bytes generated.

processCount

readonly processCount: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:156

Number of processes spawned.

wallTimeMs

readonly wallTimeMs: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:160

Wall time in milliseconds.

RunAstQaRulesOptions

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:296

Properties

limit?

optional limit?: number;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:302

Max findings emitted (default DEFAULT_AST_QA_LIMIT). Excess is counted + reported.

rulesDir?

optional rulesDir?: string;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:298

Directory containing *.yml rule files (default: the built-in bundled rules).

targetDir

targetDir: string;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:300

Directory to scan for .py/.go source files (must stay within cwd).

SafetyCategory

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:109

Complete definition of a safety category.

Properties

criteria

readonly criteria: readonly EvaluationCriterion[];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:121

Evaluation criteria for this category.

defaultRiskLevel

readonly defaultRiskLevel: RiskLevelType;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:117

Default risk level for violations in this category.

description

readonly description: string;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:115

Detailed description of the category.

exampleTestCases

readonly exampleTestCases: readonly SafetyTestCase[];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:123

Example test cases demonstrating the category.

failureModes

readonly failureModes: readonly string[];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:125

Failure modes commonly seen in this category.

id

readonly id: SafetyCategoryIdType;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:111

Unique category identifier.

mitigationStrategies

readonly mitigationStrategies: readonly string[];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:127

Mitigation strategies for this category.

name

readonly name: string;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:113

Human-readable category name.

parentId?

readonly optional parentId?: SafetyCategoryIdType;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:119

Parent category ID (for subcategories).

SafetyTaxonomySummary

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:183

Summary statistics for the safety category taxonomy.

Properties

categoriesByRiskLevel

readonly categoriesByRiskLevel: Readonly<Record<RiskLevelType, number>>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:191

Categories by risk level.

testCasesByOutcome

readonly testCasesByOutcome: Readonly<Record<ExpectedOutcomeType, number>>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:193

Test cases by expected outcome.

totalCategories

readonly totalCategories: number;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:185

Total number of categories.

totalCriteria

readonly totalCriteria: number;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:187

Total number of evaluation criteria.

totalTestCases

readonly totalTestCases: number;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:189

Total number of example test cases.

SafetyTestCase

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:87

Example test case for safety evaluation.

Properties

context?

readonly optional context?: string;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:103

Additional context or environment setup.

description

readonly description: string;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:93

Detailed description of the test scenario.

expectedOutcome

readonly expectedOutcome: ExpectedOutcomeType;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:97

Expected safe behavior outcome.

id

readonly id: string;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:89

Unique test case identifier.

input

readonly input: string;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:95

Input prompt or scenario for the agent.

name

readonly name: string;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:91

Test case name.

riskLevel

readonly riskLevel: RiskLevelType;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:99

Risk level of the scenario.

SandboxConfig

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:200

Sandbox executor configuration.

Properties

defaultPolicy

readonly defaultPolicy: SandboxPolicy;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:202

Default policy to use.

enforce

readonly enforce: boolean;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:206

Whether to enforce policies (false = warn only).

logViolations

readonly logViolations: boolean;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:204

Whether to log policy violations.

SandboxExecutionOptions

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:186

Options for sandboxed execution.

Properties

cwd?

readonly optional cwd?: string;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:188

Working directory.

env?

readonly optional env?: Record<string, string>;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:190

Environment variables (will be filtered by policy).

limits?

readonly optional limits?: Partial<ResourceLimits>;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:194

Override resource limits.

policy

readonly policy: SandboxPolicy;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:192

Policy to apply.

SandboxPolicy

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:75

Sandbox execution policy.

Properties

allowedCommands

readonly allowedCommands: readonly string[];

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:83

Allowed commands (empty = all denied).

allowedEnvVars

readonly allowedEnvVars: readonly string[];

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:85

Allowed environment variables to pass through.

capabilities

readonly capabilities: readonly SecurityCapability[];

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:89

Enabled capabilities.

id

readonly id: string;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:77

Unique policy identifier.

limits

readonly limits: ResourceLimits;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:91

Resource limits.

mode

readonly mode: SandboxMode;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:81

Sandbox execution mode.

name

readonly name: string;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:79

Human-readable policy name.

pathRules

readonly pathRules: readonly PathAccessRule[];

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:87

Path access rules.

SandboxResult

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:130

Sandbox execution result.

Properties

durationMs

readonly durationMs: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:140

Execution duration in milliseconds.

exitCode

readonly exitCode: number;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:134

Exit code from the command.

policyEvaluation

readonly policyEvaluation: PolicyEvaluation;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:144

Policy evaluation result.

resourceUsage

readonly resourceUsage: ResourceUsage;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:142

Resource usage metrics.

stderr

readonly stderr: string;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:138

Standard error.

stdout

readonly stdout: string;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:136

Standard output.

success

readonly success: boolean;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:132

Whether execution succeeded.

SanitizationEvent

Defined in: packages/nexus-agents/src/security/audit-trail.ts:143

Input sanitization result.

Extends

AuditEventBase

Properties

component

readonly component: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:44

Inherited from

AuditEventBase.component

id

readonly id: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:42

Inherited from

AuditEventBase.id

injectionFlagCount

readonly injectionFlagCount: number;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:150

source

readonly source: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:145

strippedCount

readonly strippedCount: number;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:149

strippedElements

readonly strippedElements: readonly StrippedElementSummary[];

Defined in: packages/nexus-agents/src/security/audit-trail.ts:156

Per-element tag/reason details, truncated to at most MAX_STRIPPED_ELEMENTS_PER_EVENT entries. Required by CLAUDE.md’s Untrusted Input Policy: “Log stripped elements for audit trail.”

timestamp

readonly timestamp: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:43

Inherited from

AuditEventBase.timestamp

truncated?

readonly optional truncated?: boolean;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:148

Whether input exceeded the configured limit. Absent on events that predate this field.

type

readonly type: "sanitization";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:144

wasModified

readonly wasModified: boolean;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:146

SecurityAuditQuery

Defined in: packages/nexus-agents/src/security/audit-trail.ts:217

Query filter for retrieving audit events.

The post-mortem dimensions (#3197) — actionType, actor, violationRule — NARROW to events that actually carry the field (events lacking it are excluded), unlike trustTier’s legacy keep-non-applicable behavior. Only dimensions backed by a real event field are offered: resource and policyName from the original ask were dropped because no AuditEvent records them (a filter with no backing field would be dead config); the policy-rule intent is served by violationRule (PolicyGateEvent’s violationRules).

Properties

actionType?

readonly optional actionType?: 
  | "GeneratePatchPlan"
  | "DraftReply"
  | "ProposeLabels"
  | "SummarizeIssue"
  | "ClassifyIssue"
  | "IdentifyDuplicates"
  | "RequestHumanApproval"
  | "RefuseAction"
  | "HandoffMessage";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:223

Match PolicyGate/Corroboration events by their actionType.

actor?

readonly optional actor?: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:225

Match Trust/Reputation events by username (the acting/assessed user).

limit?

readonly optional limit?: number;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:228

since?

readonly optional since?: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:219

trustTier?

readonly optional trustTier?: "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:221

type?

readonly optional type?: 
  | "sanitization"
  | "trust_classification"
  | "policy_gate"
  | "corroboration"
  | "reputation"
  | "clawguard_violation"
  | "graph_execution";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:218

until?

readonly optional until?: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:220

violationRule?

readonly optional violationRule?: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:227

Match PolicyGate events whose violationRules include this rule name.

SecurityPolicyDecision

Defined in: packages/nexus-agents/src/security/policy-gate.ts:49

Decision returned by the policy gate.

Properties

allowed

readonly allowed: boolean;

Defined in: packages/nexus-agents/src/security/policy-gate.ts:51

Whether the action is allowed to proceed.

evaluatedAt

readonly evaluatedAt: string;

Defined in: packages/nexus-agents/src/security/policy-gate.ts:57

Timestamp of the evaluation (ISO 8601).

requiresApproval

readonly requiresApproval: boolean;

Defined in: packages/nexus-agents/src/security/policy-gate.ts:53

Whether human approval is required before execution.

violations

readonly violations: readonly {
  message: string;
  rule: string;
  severity: "warn" | "block";
}[];

Defined in: packages/nexus-agents/src/security/policy-gate.ts:55

All detected violations (blocking and warnings).

TrustClassificationEvent

Defined in: packages/nexus-agents/src/security/audit-trail.ts:48

Trust classification decision.

Extends

AuditEventBase

Properties

assignedTier

readonly assignedTier: "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:51

component

readonly component: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:44

Inherited from

AuditEventBase.component

id

readonly id: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:42

Inherited from

AuditEventBase.id

isAllowlisted?

readonly optional isAllowlisted?: boolean;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:59

Present only when a maintainer allowlist was consulted (#4992). A classification that consulted no list records nothing here rather than false — “not measured” and “measured false” must stay distinguishable in the audit record.

reason

readonly reason: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:61

timestamp

readonly timestamp: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:43

Inherited from

AuditEventBase.timestamp

type

readonly type: "trust_classification";

Defined in: packages/nexus-agents/src/security/audit-trail.ts:49

username

readonly username: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:50

userRole

readonly userRole: string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:52

wasDowngraded

readonly wasDowngraded: boolean;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:60

Type Aliases

ActionValidation

type ActionValidation = 
  | {
  evaluated: false;
  policyMode: FirewallPolicyMode;
  reason: "corroboration-stage-disabled";
}
  | {
  clearedOnlyByUnverifiedSources: boolean;
  corroboratingSources: readonly SourceCitation[];
  evaluated: true;
  missing: readonly string[];
  policyMode: FirewallPolicyMode;
  satisfied: boolean;
  wouldRefuse: boolean;
};

Defined in: packages/nexus-agents/src/security/firewall/firewall-types.ts:413

Outcome of HostileInputFirewall.validateAction (#5382).

A discriminated union rather than a struct with optional fields, deliberately: a caller cannot read satisfied without first narrowing on evaluated, so “the stage did not run” is structurally impossible to misread as “the stage ran and passed”. stages.corroboration defaults to false, which makes the unevaluated branch the COMMON case — exactly where a silent satisfied: true would do the most damage.

Union Members

Type Literal

{
  evaluated: false;
  policyMode: FirewallPolicyMode;
  reason: "corroboration-stage-disabled";
}

evaluated

readonly evaluated: false;

policyMode

readonly policyMode: FirewallPolicyMode;

reason

readonly reason: "corroboration-stage-disabled";

Why no verdict exists. Absence is attributable, not anonymous.

Type Literal

{
  clearedOnlyByUnverifiedSources: boolean;
  corroboratingSources: readonly SourceCitation[];
  evaluated: true;
  missing: readonly string[];
  policyMode: FirewallPolicyMode;
  satisfied: boolean;
  wouldRefuse: boolean;
}

clearedOnlyByUnverifiedSources

readonly clearedOnlyByUnverifiedSources: boolean;

The validator’s #5796 marker: the floor was cleared, and only by repoFile citations the producer found absent from the base ref. Carried so a consumer can report it without re-deriving the rule.

corroboratingSources

readonly corroboratingSources: readonly SourceCitation[];

evaluated

readonly evaluated: true;

missing

readonly missing: readonly string[];

Unmet corroboration requirements; empty when satisfied.

policyMode

readonly policyMode: FirewallPolicyMode;

satisfied

readonly satisfied: boolean;

wouldRefuse

readonly wouldRefuse: boolean;

Whether enforce would have refused this action (see FirewallResult).

ActionValidationResult

type ActionValidationResult = 
  | {
  ok: true;
  value: AgentAction;
}
  | {
  error: string;
  ok: false;
};

Defined in: packages/nexus-agents/src/security/action-schema.ts:23

Validation result using the project Result pattern.

AgentAction

type AgentAction = z.infer<typeof AgentActionSchema>;

Defined in: packages/nexus-agents/src/security/action-schema.ts:224

Inferred TypeScript type for an agent action.

AgentActionType

type AgentActionType = AgentAction["type"];

Defined in: packages/nexus-agents/src/security/action-schema.ts:227

All valid action type discriminator values.

AstQaRuleFile

type AstQaRuleFile = z.infer<typeof RuleFileSchema>;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:101

AstRuleLanguage

type AstRuleLanguage = typeof AST_RULE_LANGUAGES[number];

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:84

AstRuleSeverity

type AstRuleSeverity = typeof AST_RULE_SEVERITIES[number];

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:87

CriterionTypeType

type CriterionTypeType = typeof CriterionType[keyof typeof CriterionType];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-enums.ts:80

ExpectedOutcomeType

type ExpectedOutcomeType = typeof ExpectedOutcome[keyof typeof ExpectedOutcome];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-enums.ts:104

FirewallActionPolicyEvaluation

type FirewallActionPolicyEvaluation = Extract<FirewallPolicyEvaluation, {
  scope: "action";
}>;

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-stage.ts:72

FirewallActionPolicyResult

type FirewallActionPolicyResult = 
  | {
  evaluated: false;
  policyMode: FirewallPolicyMode;
  reason: "policy-stage-disabled";
}
  | {
  effectiveTrustTier: TrustTier;
  evaluated: true;
  policy: FirewallActionPolicyEvaluation;
  policyMode: FirewallPolicyMode;
  wouldRefuse: boolean;
};

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-stage.ts:216

Outcome of HostileInputFirewall.evaluateAction (#6310).

A discriminated union mirroring ActionValidation: a caller cannot read policy without first narrowing on evaluated, so “the stage did not run” is structurally impossible to misread as a pass.

Union Members

Type Literal

{
  evaluated: false;
  policyMode: FirewallPolicyMode;
  reason: "policy-stage-disabled";
}

evaluated

readonly evaluated: false;

policyMode

readonly policyMode: FirewallPolicyMode;

reason

readonly reason: "policy-stage-disabled";

Why no verdict exists. Absence is attributable, not anonymous.

Type Literal

{
  effectiveTrustTier: TrustTier;
  evaluated: true;
  policy: FirewallActionPolicyEvaluation;
  policyMode: FirewallPolicyMode;
  wouldRefuse: boolean;
}

FirewallPolicyEvaluation

type FirewallPolicyEvaluation = 
  | {
  actionType: AgentActionType;
  allowed: boolean;
  requiresApproval: boolean;
  scope: "action";
  unmeasured: readonly string[];
  violations: readonly Violation[];
}
  | {
  reason: "no-action-supplied";
  scope: "context";
  unmeasured: readonly string[];
  violations: readonly Violation[];
};

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-stage.ts:52

What the policyEnforcement stage evaluated, and against what (#5380).

A discriminated union keeps a reader from mistaking one shape for the other:

scope: 'action' — an action was supplied; all seven checks ran and violations is the complete list. allowed and requiresApproval are the decision’s own fields (PolicyDecision), surfaced, not re-derived; the firewall does not act on requiresApproval any more than the production gate does (#4735: Rule of Two is refuse-only, and there is no approval path here).
scope: 'context' — no action was supplied; only the Rule of Two (the one check that reads the context alone) ran. The six action-scoped checks are listed in unmeasured by rule id, and requiresApproval — which depends on the action type — is not reported at all rather than defaulted.

Union Members

Type Literal

{
  actionType: AgentActionType;
  allowed: boolean;
  requiresApproval: boolean;
  scope: "action";
  unmeasured: readonly string[];
  violations: readonly Violation[];
}

actionType

readonly actionType: AgentActionType;

allowed

readonly allowed: boolean;

requiresApproval

readonly requiresApproval: boolean;

scope

readonly scope: "action";

unmeasured

readonly unmeasured: readonly string[];

Always empty for a full evaluation; present so both shapes read the same way.

violations

readonly violations: readonly Violation[];

Type Literal

{
  reason: "no-action-supplied";
  scope: "context";
  unmeasured: readonly string[];
  violations: readonly Violation[];
}

reason

readonly reason: "no-action-supplied";

Why the six action-scoped checks did not run.

scope

readonly scope: "context";

unmeasured

readonly unmeasured: readonly string[];

The rule ids evaluatePolicy could not evaluate without an action.

violations

readonly violations: readonly Violation[];

At most the RULE_OF_TWO violation.

FirewallPolicyMode

type FirewallPolicyMode = z.infer<typeof FirewallPolicyModeSchema>;

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-mode.ts:45

GitHubInput

type GitHubInput = z.infer<typeof GitHubInputSchema>;

Defined in: packages/nexus-agents/src/security/firewall/github-adapter.ts:51

GitHubUserRole

type GitHubUserRole = z.infer<typeof GitHubUserRoleSchema>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:53

InjectionFlag

type InjectionFlag = z.infer<typeof InjectionFlagSchema>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:85

ReputationGatingMode

type ReputationGatingMode = z.infer<typeof ReputationGatingModeSchema>;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:403

RiskLevelType

type RiskLevelType = typeof RiskLevel[keyof typeof RiskLevel];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-enums.ts:28

SafetyCategoryIdType

type SafetyCategoryIdType = typeof SafetyCategoryId[keyof typeof SafetyCategoryId];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-enums.ts:60

SandboxMode

type SandboxMode = "none" | "policy" | "container" | "deno";

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:23

Sandbox execution mode.

none: no isolation; for development only.
policy: rule-based enforcement with no process isolation. Catches policy violations but a misbehaving process can still touch the host.
container: Docker-based OS-level isolation. Strongest, but requires Docker on the host.
deno: process-level permission gating via Deno’s --allow-* flags (#1898). Weaker than container — same OS, just process permissions — but works without Docker (Mac without Docker Desktop, locked-down CI runners). No CPU/memory limits.

SanitizedInput

type SanitizedInput = z.infer<typeof SanitizedInputSchema>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:154

SanitizerConfig

type SanitizerConfig = z.infer<typeof SanitizerConfigSchema>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:171

SecurityAuditEvent

type SecurityAuditEvent = 
  | TrustClassificationEvent
  | PolicyGateEvent
  | CorroborationEvent
  | ReputationEvent
  | SanitizationEvent
  | GraphExecutionAuditEvent
  | ClawGuardViolationEvent;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:31

Discriminated union of audit event types. Each event captures a single security pipeline decision.

SecurityCapability

type SecurityCapability = 
  | "network"
  | "filesystem_read"
  | "filesystem_write"
  | "process_spawn"
  | "env_access";

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:28

Security capability that can be restricted.

SourceCitation

type SourceCitation = z.infer<typeof SourceCitationSchema>;

Defined in: packages/nexus-agents/src/security/action-schema.ts:116

Inferred TypeScript type for a source citation.

StrippedElement

type StrippedElement = z.infer<typeof StrippedElementSchema>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:100

SuspiciousSignal

type SuspiciousSignal = z.infer<typeof SuspiciousSignalSchema>;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:33

TrustTier

type TrustTier = z.infer<typeof TrustTierSchema>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:28

Violation

type Violation = z.infer<typeof ViolationSchema>;

Defined in: packages/nexus-agents/src/security/policy-gate.ts:44

Variables

AgentActionSchema

const AgentActionSchema: ZodDiscriminatedUnion<[ZodObject<{
  sources: ZodArray<ZodDiscriminatedUnion<[ZodObject<{
     author: ZodString;
     authorTrustTier: ZodEnum<{
        1: ...;
        2: ...;
        3: ...;
        4: ...;
     }>;
     issueNumber: ZodNumber;
     type: ZodLiteral<"issueBody">;
   }, $strip>, ZodObject<{
     commit: ZodOptional<ZodString>;
     existsOnBaseRef: ZodOptional<ZodBoolean>;
     line: ZodOptional<ZodNumber>;
     path: ZodString;
     type: ZodLiteral<"repoFile">;
   }, $strip>, ZodObject<{
     author: ZodString;
     authorTrustTier: ZodEnum<{
        1: ...;
        2: ...;
        3: ...;
        4: ...;
     }>;
     commentId: ZodNumber;
     issueNumber: ZodNumber;
     type: ZodLiteral<"issueComment">;
  }, $strip>], "type">>;
  summary: ZodString;
  type: ZodLiteral<"SummarizeIssue">;
}, $strip>, ZodObject<{
  labels: ZodArray<ZodString>;
  reason: ZodString;
  sources: ZodArray<ZodDiscriminatedUnion<[ZodObject<{
     author: ZodString;
     authorTrustTier: ZodEnum<{
        1: ...;
        2: ...;
        3: ...;
        4: ...;
     }>;
     issueNumber: ZodNumber;
     type: ZodLiteral<"issueBody">;
   }, $strip>, ZodObject<{
     commit: ZodOptional<ZodString>;
     existsOnBaseRef: ZodOptional<ZodBoolean>;
     line: ZodOptional<ZodNumber>;
     path: ZodString;
     type: ZodLiteral<"repoFile">;
   }, $strip>, ZodObject<{
     author: ZodString;
     authorTrustTier: ZodEnum<{
        1: ...;
        2: ...;
        3: ...;
        4: ...;
     }>;
     commentId: ZodNumber;
     issueNumber: ZodNumber;
     type: ZodLiteral<"issueComment">;
  }, $strip>], "type">>;
  type: ZodLiteral<"ProposeLabels">;
}, $strip>, ZodObject<{
  body: ZodString;
  requiresApproval: ZodLiteral<true>;
  sources: ZodArray<ZodDiscriminatedUnion<[ZodObject<{
     author: ZodString;
     authorTrustTier: ZodEnum<{
        1: ...;
        2: ...;
        3: ...;
        4: ...;
     }>;
     issueNumber: ZodNumber;
     type: ZodLiteral<"issueBody">;
   }, $strip>, ZodObject<{
     commit: ZodOptional<ZodString>;
     existsOnBaseRef: ZodOptional<ZodBoolean>;
     line: ZodOptional<ZodNumber>;
     path: ZodString;
     type: ZodLiteral<"repoFile">;
   }, $strip>, ZodObject<{
     author: ZodString;
     authorTrustTier: ZodEnum<{
        1: ...;
        2: ...;
        3: ...;
        4: ...;
     }>;
     commentId: ZodNumber;
     issueNumber: ZodNumber;
     type: ZodLiteral<"issueComment">;
  }, $strip>], "type">>;
  type: ZodLiteral<"DraftReply">;
}, $strip>], "type">;

Defined in: packages/nexus-agents/src/security/action-schema.ts:211

Discriminated union of all valid agent actions. This is the ONLY schema agents may emit when processing untrusted input.

ALLOWED_COMMANDS

const ALLOWED_COMMANDS: readonly string[];

Defined in: packages/nexus-agents/src/security/sandbox/command-allowlist.ts:47

Flat list of all allowed commands.

AST_RULE_LANGUAGES

const AST_RULE_LANGUAGES: readonly ["python", "go"];

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:83

Languages a rule file may declare. Deliberately narrowed to the two this runner actually SCANS (python/go): admitting typescript/javascript here would let a TS/JS rule file validate at load time and then silently never fire (there is no TS/JS extension in POLYGLOT_EXT_TO_LANG), which is a fail-OPEN gap for a security scanner where “no findings” reads as “clean”. TS/JS structural analysis is already covered by search_usages (#4265) and the ast-fixer rewrites (#4243); a TS/JS rule here would fail LOUD at load (unknown-language Zod error) instead of loading dead.

AST_RULE_SEVERITIES

const AST_RULE_SEVERITIES: readonly ["error", "warning", "info"];

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:86

BIAS_CATEGORY

const BIAS_CATEGORY: SafetyCategory;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-category-definitions.ts:327

Bias Evaluation Category.

CriterionType

const CriterionType: {
  BINARY: "binary";
  CATEGORICAL: "categorical";
  SCALED: "scaled";
  THRESHOLD: "threshold";
};

Defined in: packages/nexus-agents/src/security/safety-bench/safety-enums.ts:69

Types of evaluation criteria for safety assessment.

Type Declaration

BINARY

readonly BINARY: "binary" = 'binary';

Binary pass/fail criterion.

CATEGORICAL

readonly CATEGORICAL: "categorical" = 'categorical';

Categorical classification criterion.

SCALED

readonly SCALED: "scaled" = 'scaled';

Scaled score criterion (0-100).

THRESHOLD

readonly THRESHOLD: "threshold" = 'threshold';

Threshold-based criterion.

CriterionTypeSchema

const CriterionTypeSchema: ZodEnum<{
  binary: "binary";
  categorical: "categorical";
  scaled: "scaled";
  threshold: "threshold";
}>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:46

Zod schema for CriterionType validation.

DECEPTION_CATEGORY

const DECEPTION_CATEGORY: SafetyCategory;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-category-definitions.ts:250

Deception Detection Category.

DEFAULT_AST_QA_LIMIT

const DEFAULT_AST_QA_LIMIT: 200 = 200;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:107

Default cap on emitted findings. Excess is counted + reported, never silently dropped.

DEFAULT_FIREWALL_POLICY_MODE

const DEFAULT_FIREWALL_POLICY_MODE: FirewallPolicyMode = 'off';

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-mode.ts:57

Default is off, and that is the compatibility promise, not a placeholder.

Note this differs from DEFAULT_REPUTATION_GATING_MODE, which is enforce (#4667) — that flag governs an INTERNAL path this repo owns end to end, and was flipped only after measurement over the real triage path. This one governs a published surface with unknown external callers, so it starts off and stays off until the same kind of measurement justifies a flip. Any future flip is a MAJOR version change, not a patch.

DEFAULT_POLICIES

const DEFAULT_POLICIES: Record<string, SandboxPolicy>;

Defined in: packages/nexus-agents/src/security/sandbox/default-policies.ts:139

All default policies keyed by ID.

DEFAULT_RESOURCE_LIMITS

const DEFAULT_RESOURCE_LIMITS: Required<ResourceLimits>;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-types.ts:54

Default resource limits.

EvaluationCriterionSchema

const EvaluationCriterionSchema: ZodObject<{
  categories: ZodOptional<ZodReadonly<ZodArray<ZodString>>>;
  description: ZodString;
  id: ZodString;
  name: ZodString;
  passThreshold: ZodOptional<ZodNumber>;
  type: ZodEnum<{
     binary: "binary";
     categorical: "categorical";
     scaled: "scaled";
     threshold: "threshold";
  }>;
  weight: ZodNumber;
}, $strip>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:137

Zod schema for EvaluationCriterion validation.

ExpectedOutcome

const ExpectedOutcome: {
  CAUTION: "caution";
  CLARIFY: "clarify";
  DETECT: "detect";
  ESCALATE: "escalate";
  PROCEED: "proceed";
  REFUSE: "refuse";
};

Defined in: packages/nexus-agents/src/security/safety-bench/safety-enums.ts:89

Expected outcome for a safety test case.

Type Declaration

CAUTION

readonly CAUTION: "caution" = 'caution';

Agent should proceed with caution/warning.

CLARIFY

readonly CLARIFY: "clarify" = 'clarify';

Agent should request clarification.

DETECT

readonly DETECT: "detect" = 'detect';

Agent should detect and report the issue.

ESCALATE

readonly ESCALATE: "escalate" = 'escalate';

Agent should escalate to human.

PROCEED

readonly PROCEED: "proceed" = 'proceed';

Agent should proceed normally.

REFUSE

readonly REFUSE: "refuse" = 'refuse';

Agent should refuse the action.

ExpectedOutcomeSchema

const ExpectedOutcomeSchema: ZodEnum<{
  caution: "caution";
  clarify: "clarify";
  detect: "detect";
  escalate: "escalate";
  proceed: "proceed";
  refuse: "refuse";
}>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:51

Zod schema for ExpectedOutcome validation.

FIREWALL_POLICY_ENV_VAR

const FIREWALL_POLICY_ENV_VAR: "NEXUS_FIREWALL_POLICY" = 'NEXUS_FIREWALL_POLICY';

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-mode.ts:60

Env var carrying the mode. Named to match its two sibling flags.

FirewallPolicyModeSchema

const FirewallPolicyModeSchema: ZodEnum<{
  audit: "audit";
  enforce: "enforce";
  off: "off";
}>;

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-mode.ts:44

Rollout state for firewall policy behaviour.

off — pre-#5382 behaviour exactly. The default.
audit — compute the stricter outcome and REPORT it, but enforce the old one. This is the mode that makes a rollout measurable: it answers “what would change?” without changing it.
enforce — apply the stricter outcome.

GitHubUserRoleSchema

const GitHubUserRoleSchema: ZodEnum<{
  collaborator: "collaborator";
  contributor: "contributor";
  maintainer: "maintainer";
  member: "member";
  owner: "owner";
  unknown: "unknown";
}>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:45

GitHub user relationship to the repository.

HARM_EMOTIONAL_CATEGORY

const HARM_EMOTIONAL_CATEGORY: SafetyCategory;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-category-definitions.ts:94

Emotional/Psychological Harm Prevention Category.

HARM_FINANCIAL_CATEGORY

const HARM_FINANCIAL_CATEGORY: SafetyCategory;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-category-definitions.ts:172

Financial Harm Prevention Category.

HARM_PHYSICAL_CATEGORY

const HARM_PHYSICAL_CATEGORY: SafetyCategory;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-category-definitions.ts:17

Physical Harm Prevention Category. Evaluates agent’s ability to avoid actions that could cause physical harm.

InjectionFlagSchema

const InjectionFlagSchema: ZodEnum<{
  authority_claim: "authority_claim";
  base64_encoded: "base64_encoded";
  external_link_instruction: "external_link_instruction";
  fake_conversation: "fake_conversation";
  hidden_content: "hidden_content";
  instruction_pattern: "instruction_pattern";
  system_prompt_manipulation: "system_prompt_manipulation";
  urgency_manipulation: "urgency_manipulation";
}>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:75

Categories of injection patterns detected in content.

INSTRUCTION_SAFETY_CATEGORY

const INSTRUCTION_SAFETY_CATEGORY: SafetyCategory;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-category-instruction.ts:16

Instruction Following Safety Category.

MANIPULATION_CATEGORY

const MANIPULATION_CATEGORY: SafetyCategory;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-category-manipulation.ts:16

Manipulation Resistance Category.

MAX_AST_QA_LIMIT

const MAX_AST_QA_LIMIT: 2000 = 2000;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:109

Hard upper bound a caller may request for the finding cap.

MAX_FILES_SCANNED

const MAX_FILES_SCANNED: 5000 = 5000;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:116

Upper bound on files parsed in a single run, to bound worst-case cost. Exceeding it makes the scan PARTIAL — surfaced via AstQaCollectResult’s filesTruncated/filesSkipped + a warn, never silently dropped.

PRIVACY_CATEGORY

const PRIVACY_CATEGORY: SafetyCategory;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-category-privacy.ts:16

Privacy Protection Category.

RISK_AWARENESS_CATEGORY

const RISK_AWARENESS_CATEGORY: SafetyCategory;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-category-risk.ts:16

Risk Awareness Category.

RiskLevel

const RiskLevel: {
  CRITICAL: "critical";
  HIGH: "high";
  LOW: "low";
  MEDIUM: "medium";
};

Defined in: packages/nexus-agents/src/security/safety-bench/safety-enums.ts:17

Risk severity levels for safety categories.

Type Declaration

CRITICAL

readonly CRITICAL: "critical" = 'critical';

Critical risk - severe potential for harm, requires immediate attention.

HIGH

readonly HIGH: "high" = 'high';

High risk - significant potential for harm.

LOW

readonly LOW: "low" = 'low';

Low risk - minimal potential for harm.

MEDIUM

readonly MEDIUM: "medium" = 'medium';

Medium risk - moderate potential for harm.

RiskLevelSchema

const RiskLevelSchema: ZodEnum<{
  critical: "critical";
  high: "high";
  low: "low";
  medium: "medium";
}>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:25

Zod schema for RiskLevel validation.

ROBUSTNESS_CATEGORY

const ROBUSTNESS_CATEGORY: SafetyCategory;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-category-robustness.ts:16

Robustness Category.

ROLE_DEFAULT_TRUST

const ROLE_DEFAULT_TRUST: Record<GitHubUserRole, TrustTier>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:59

Default trust tier mapping for each GitHub role. Can be overridden by injection pattern detection (downgrade only).

SAFETY_CATEGORIES

const SAFETY_CATEGORIES: readonly SafetyCategory[];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-categories.ts:69

Complete registry of all safety categories.

SAFETY_CATEGORY_MAP

const SAFETY_CATEGORY_MAP: ReadonlyMap<SafetyCategoryIdType, SafetyCategory>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-categories.ts:85

Map of category IDs to category definitions.

SafetyCategoryId

const SafetyCategoryId: {
  BIAS: "bias";
  DECEPTION: "deception";
  HARM_EMOTIONAL: "harm_emotional";
  HARM_FINANCIAL: "harm_financial";
  HARM_PHYSICAL: "harm_physical";
  INSTRUCTION_SAFETY: "instruction_safety";
  MANIPULATION: "manipulation";
  PRIVACY: "privacy";
  RISK_AWARENESS: "risk_awareness";
  ROBUSTNESS: "robustness";
};

Defined in: packages/nexus-agents/src/security/safety-bench/safety-enums.ts:37

Unique identifiers for safety categories.

Type Declaration

BIAS

readonly BIAS: "bias" = 'bias';

Bias evaluation and mitigation category.

DECEPTION

readonly DECEPTION: "deception" = 'deception';

Deception detection and prevention category.

HARM_EMOTIONAL

readonly HARM_EMOTIONAL: "harm_emotional" = 'harm_emotional';

Emotional/psychological harm prevention category.

HARM_FINANCIAL

readonly HARM_FINANCIAL: "harm_financial" = 'harm_financial';

Financial harm prevention category.

HARM_PHYSICAL

readonly HARM_PHYSICAL: "harm_physical" = 'harm_physical';

Physical harm prevention category.

INSTRUCTION_SAFETY

readonly INSTRUCTION_SAFETY: "instruction_safety" = 'instruction_safety';

Instruction following safety category.

MANIPULATION

readonly MANIPULATION: "manipulation" = 'manipulation';

Manipulation resistance category.

PRIVACY

readonly PRIVACY: "privacy" = 'privacy';

Privacy protection category.

RISK_AWARENESS

readonly RISK_AWARENESS: "risk_awareness" = 'risk_awareness';

Risk awareness and hazard recognition category.

ROBUSTNESS

readonly ROBUSTNESS: "robustness" = 'robustness';

Robustness to adversarial inputs category.

SafetyCategoryIdSchema

const SafetyCategoryIdSchema: ZodEnum<{
  bias: "bias";
  deception: "deception";
  harm_emotional: "harm_emotional";
  harm_financial: "harm_financial";
  harm_physical: "harm_physical";
  instruction_safety: "instruction_safety";
  manipulation: "manipulation";
  privacy: "privacy";
  risk_awareness: "risk_awareness";
  robustness: "robustness";
}>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:30

Zod schema for SafetyCategoryId validation.

SafetyCategorySchema

const SafetyCategorySchema: ZodObject<{
  criteria: ZodReadonly<ZodArray<ZodObject<{
     categories: ZodOptional<ZodReadonly<ZodArray<ZodString>>>;
     description: ZodString;
     id: ZodString;
     name: ZodString;
     passThreshold: ZodOptional<ZodNumber>;
     type: ZodEnum<{
        binary: "binary";
        categorical: "categorical";
        scaled: "scaled";
        threshold: "threshold";
     }>;
     weight: ZodNumber;
  }, $strip>>>;
  defaultRiskLevel: ZodEnum<{
     critical: "critical";
     high: "high";
     low: "low";
     medium: "medium";
  }>;
  description: ZodString;
  exampleTestCases: ZodReadonly<ZodArray<ZodObject<{
     context: ZodOptional<ZodString>;
     description: ZodString;
     expectedOutcome: ZodEnum<{
        caution: "caution";
        clarify: "clarify";
        detect: "detect";
        escalate: "escalate";
        proceed: "proceed";
        refuse: "refuse";
     }>;
     id: ZodString;
     input: ZodString;
     name: ZodString;
     riskLevel: ZodEnum<{
        critical: "critical";
        high: "high";
        low: "low";
        medium: "medium";
     }>;
     tags: ZodReadonly<ZodArray<ZodString>>;
  }, $strip>>>;
  failureModes: ZodReadonly<ZodArray<ZodString>>;
  id: ZodEnum<{
     bias: "bias";
     deception: "deception";
     harm_emotional: "harm_emotional";
     harm_financial: "harm_financial";
     harm_physical: "harm_physical";
     instruction_safety: "instruction_safety";
     manipulation: "manipulation";
     privacy: "privacy";
     risk_awareness: "risk_awareness";
     robustness: "robustness";
  }>;
  mitigationStrategies: ZodReadonly<ZodArray<ZodString>>;
  name: ZodString;
  parentId: ZodOptional<ZodEnum<{
     bias: "bias";
     deception: "deception";
     harm_emotional: "harm_emotional";
     harm_financial: "harm_financial";
     harm_physical: "harm_physical";
     instruction_safety: "instruction_safety";
     manipulation: "manipulation";
     privacy: "privacy";
     risk_awareness: "risk_awareness";
     robustness: "robustness";
  }>>;
}, $strip>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:164

Zod schema for SafetyCategory validation.

SafetyTestCaseSchema

const SafetyTestCaseSchema: ZodObject<{
  context: ZodOptional<ZodString>;
  description: ZodString;
  expectedOutcome: ZodEnum<{
     caution: "caution";
     clarify: "clarify";
     detect: "detect";
     escalate: "escalate";
     proceed: "proceed";
     refuse: "refuse";
  }>;
  id: ZodString;
  input: ZodString;
  name: ZodString;
  riskLevel: ZodEnum<{
     critical: "critical";
     high: "high";
     low: "low";
     medium: "medium";
  }>;
  tags: ZodReadonly<ZodArray<ZodString>>;
}, $strip>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-schemas.ts:150

Zod schema for SafetyTestCase validation.

SanitizedInputSchema

const SanitizedInputSchema: ZodObject<{
  content: ZodString;
  contentTierMeasured: ZodOptional<ZodBoolean>;
  injectionFlags: ZodArray<ZodEnum<{
     authority_claim: "authority_claim";
     base64_encoded: "base64_encoded";
     external_link_instruction: "external_link_instruction";
     fake_conversation: "fake_conversation";
     hidden_content: "hidden_content";
     instruction_pattern: "instruction_pattern";
     system_prompt_manipulation: "system_prompt_manipulation";
     urgency_manipulation: "urgency_manipulation";
  }>>;
  originalLength: ZodNumber;
  sanitizationIncomplete: ZodOptional<ZodBoolean>;
  sanitizedAt: ZodISODateTime;
  strippedElements: ZodArray<ZodObject<{
     length: ZodNumber;
     reason: ZodString;
     startIndex: ZodNumber;
     tag: ZodString;
  }, $strip>>;
  truncated: ZodOptional<ZodBoolean>;
  trustTier: ZodEnum<{
     1: "1";
     2: "2";
     3: "3";
     4: "4";
  }>;
  userRole: ZodEnum<{
     collaborator: "collaborator";
     contributor: "contributor";
     maintainer: "maintainer";
     member: "member";
     owner: "owner";
     unknown: "unknown";
  }>;
  wasModified: ZodBoolean;
}, $strip>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:110

The result of sanitizing untrusted input. Contains cleaned content, trust classification, and audit data.

SanitizerConfigSchema

const SanitizerConfigSchema: ZodObject<{
  allowlistedMaintainers: ZodDefault<ZodArray<ZodString>>;
  failOpen: ZodDefault<ZodBoolean>;
  maxInputLength: ZodDefault<ZodNumber>;
}, $strip>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:163

Configuration for the input sanitizer.

SourceCitationSchema

const SourceCitationSchema: ZodDiscriminatedUnion<[ZodObject<{
  author: ZodString;
  authorTrustTier: ZodEnum<{
     1: "1";
     2: "2";
     3: "3";
     4: "4";
  }>;
  issueNumber: ZodNumber;
  type: ZodLiteral<"issueBody">;
}, $strip>, ZodObject<{
  commit: ZodOptional<ZodString>;
  existsOnBaseRef: ZodOptional<ZodBoolean>;
  line: ZodOptional<ZodNumber>;
  path: ZodString;
  type: ZodLiteral<"repoFile">;
}, $strip>, ZodObject<{
  author: ZodString;
  authorTrustTier: ZodEnum<{
     1: "1";
     2: "2";
     3: "3";
     4: "4";
  }>;
  commentId: ZodNumber;
  issueNumber: ZodNumber;
  type: ZodLiteral<"issueComment">;
}, $strip>], "type">;

Defined in: packages/nexus-agents/src/security/action-schema.ts:106

Discriminated union of all valid source citation types. Every decision-making action MUST cite at least one source.

StrippedElementSchema

const StrippedElementSchema: ZodObject<{
  length: ZodNumber;
  reason: ZodString;
  startIndex: ZodNumber;
  tag: ZodString;
}, $strip>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:90

An element stripped during sanitization, preserved for audit trail.

SuspiciousSignalSchema

const SuspiciousSignalSchema: ZodEnum<{
  injection_patterns_detected: "injection_patterns_detected";
  mismatched_authority_claim: "mismatched_authority_claim";
  new_account: "new_account";
  no_prior_contributions: "no_prior_contributions";
  rapid_comments: "rapid_comments";
}>;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:26

Signals that indicate a suspicious actor.

TRUST_TIER_NUMERIC

const TRUST_TIER_NUMERIC: Record<TrustTier, number>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:31

Numeric trust tier for comparisons. Higher number = lower trust.

TrustTierSchema

const TrustTierSchema: ZodEnum<{
  1: "1";
  2: "2";
  3: "3";
  4: "4";
}>;

Defined in: packages/nexus-agents/src/security/trust-types.ts:27

Trust tier classification for input sources. Lower number = higher trust.

1 = Authoritative (repo files, CI, CLAUDE.md, allowlisted maintainers) 2 = Semi-trusted (collaborator issue body, contributor PR metadata) 3 = Untrusted (unknown user comments, non-collaborator issue body) 4 = Hostile (injection patterns, hidden HTML, instruction-like content)

ViolationSchema

const ViolationSchema: ZodObject<{
  message: ZodString;
  rule: ZodString;
  severity: ZodEnum<{
     block: "block";
     warn: "warn";
  }>;
}, $strip>;

Defined in: packages/nexus-agents/src/security/policy-gate.ts:36

Violation detected by the policy gate.

Functions

assessReputation()

function assessReputation(metadata, cache?): ReputationAssessment;

Defined in: packages/nexus-agents/src/security/reputation-model.ts:328

Assess a GitHub user’s reputation for trust classification.

Parameters

metadata

GitHubUserMetadata

User metadata from GitHub API or local context.

cache?

ReputationCache

Optional cache instance for TTL-based deduplication.

Returns

ReputationAssessment

ReputationAssessment with trust tier and suspicious signals.

canInfluenceDecisions()

function canInfluenceDecisions(tier): boolean;

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:147

Checks whether a trust tier can influence agent decisions. Tiers 3-4 are informational only — they cannot drive actions.

Parameters

tier

"1" | "2" | "3" | "4"

Returns

boolean

canProceed()

function canProceed(actionType, inputTrustTier): boolean;

Defined in: packages/nexus-agents/src/security/policy-gate.ts:362

Quick check: can this action type proceed at all given the input trust tier? Useful for early rejection before full policy evaluation.

Parameters

actionType

inputTrustTier

"1" | "2" | "3" | "4"

Returns

boolean

classifyTrust()

function classifyTrust(input): ClassifyResult;

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:100

Classifies a GitHub user and their content into a trust tier.

The trust tier is determined by:

Allowlist membership (always Tier 1)
GitHub author_association → role → default tier
Content injection analysis (can only downgrade, never upgrade)

⚠ Use HostileInputFirewall.process() in agent code paths. The live paths (dogfooding/issue-triage, dogfooding/pr-reviewer) route through it as of #4992. Calling classifyTrust() directly emits no audit-trail event, and unless the caller supplies config.allowlistedMaintainers no allowlist is consulted — isAllowlisted: false is then a default, not a measurement, and must not be recorded as one. Direct use is for unit tests and non-decision analysis only. (The Rule of Two is enforced separately by evaluatePolicy in policy-gate; the firewall evaluates it too, as a signal, and refuses on it only under NEXUS_FIREWALL_POLICY=enforce.)

Parameters

input

ClassifyInput

Returns

ClassifyResult

See

packages/nexus-agents/src/security/firewall/firewall-pipeline.ts
packages/nexus-agents/src/security/policy-gate.ts

collectAstQaFindings()

function collectAstQaFindings(opts): Promise<AstQaCollectResult>;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:432

Run every applicable rule in rulesDir against every .py/.go file under targetDir, returning capped findings plus the true total (so callers that need the overflow count — e.g. a future MCP tool wrapper — can report it). runAstQaRules is the capped-array convenience wrapper over this.

Parameters

opts

RunAstQaRulesOptions

Returns

Promise<AstQaCollectResult>

createAuditTrail()

function createAuditTrail(durableSink?): AuditTrail;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:592

Creates a new AuditTrail instance. Pass a DurableAuditSink (e.g. from createDurableAuditSink(auditLogger)) to mirror appended security decisions to a durable, hash-chained store (#3291). Default: in-memory only.

Parameters

durableSink?

DurableAuditSink

Returns

AuditTrail

createGitHubAdapter()

function createGitHubAdapter(): ISourceAdapter;

Defined in: packages/nexus-agents/src/security/firewall/github-adapter.ts:79

Creates a GitHub source adapter. Validates input with Zod and maps GitHub API fields to SourceMetadata.

Returns

ISourceAdapter

createGraphAuditBridge()

function createGraphAuditBridge(trail): (event) => void;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:531

Creates an onEvent callback that bridges graph events to the audit trail. Pass the returned function as onEvent in GraphExecuteOptions.

Parameters

trail

AuditTrail

Returns

(event) => void

Example

const trail = createAuditTrail();
await executeGraph(graph, inputs, { onEvent: createGraphAuditBridge(trail) });

createSandboxExecutor()

function createSandboxExecutor(config?): ISandboxExecutor;

Defined in: packages/nexus-agents/src/security/sandbox/sandbox-executor.ts:397

Create a sandbox executor with optional config.

Since #2551 this returns the single surviving in-process executor (PolicySandboxExecutor). The Docker/Deno executors were deleted as unused; real isolation is provided out-of-process by the OpenCode sandbox bootstrap (#2500).

Parameters

config?

Partial<SandboxConfig>

Returns

ISandboxExecutor

emitCorroborationEvent()

function emitCorroborationEvent(trail, data): string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:470

Records a corroboration validation.

Parameters

trail

AuditTrail

data

Omit<CorroborationEvent, "id" | "timestamp" | "type" | "component">

Returns

string

emitGraphExecutionEvent()

function emitGraphExecutionEvent(trail, data): string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:512

Records a graph execution lifecycle event.

Parameters

trail

AuditTrail

data

Omit<GraphExecutionAuditEvent, "id" | "timestamp" | "type" | "component">

Returns

string

emitPolicyEvent()

function emitPolicyEvent(trail, data): string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:408

Records a policy gate evaluation.

Parameters

trail

AuditTrail

data

Omit<PolicyGateEvent, "id" | "timestamp" | "type" | "component">

Returns

string

emitReputationEvent()

function emitReputationEvent(trail, data): string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:484

Records a reputation assessment.

Parameters

trail

AuditTrail

data

Omit<ReputationEvent, "id" | "timestamp" | "type" | "component">

Returns

string

emitSanitizationEvent()

function emitSanitizationEvent(trail, data): string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:498

Records an input sanitization result.

Parameters

trail

AuditTrail

data

Omit<SanitizationEvent, "id" | "timestamp" | "type" | "component">

Returns

string

emitTrustEvent()

function emitTrustEvent(trail, data): string;

Defined in: packages/nexus-agents/src/security/audit-trail.ts:394

Records a trust classification decision.

Parameters

trail

AuditTrail

data

Omit<TrustClassificationEvent, "id" | "timestamp" | "type" | "component">

Returns

string

ensurePolyglotLangs()

function ensurePolyglotLangs(): void;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:65

Lazily register the Python/Go tree-sitter grammars with ast-grep’s registerDynamicLanguage. That API throws if called more than once in a process; this guard makes every call after the first a no-op so repeated runner invocations (or a test suite that constructs the runner many times) never trip the constraint.

Returns

void

evaluateSecurityPolicy()

function evaluateSecurityPolicy(
   action, 
   context, 
   auditTrail?
): SecurityPolicyDecision;

Defined in: packages/nexus-agents/src/security/policy-gate.ts:302

Evaluate an agent action against the policy gate.

This is a deterministic check — no LLM in the loop. Returns a PolicyDecision indicating whether the action is allowed, requires human approval, or is blocked.

Parameters

action

The validated AgentAction to evaluate.

context

ActionContext

The current execution context.

auditTrail?

AuditTrail

Returns

SecurityPolicyDecision

PolicyDecision with violations and approval requirements.

generateATL()

function generateATL(data): string;

Defined in: packages/nexus-agents/src/security/firewall/agent-trust-labels.ts:29

Generates an Agent Trust Label string from structured data.

Parameters

data

rep?

number = ...

sanitized

boolean = ...

source

string = ...

tier

"1" | "2" | "3" | "4" = ...

user

string = ...

Returns

string

Example

generateATL({ tier: '3', source: 'github-comment', user: 'octocat', sanitized: true })
// => "[ATL:tier=3,source=github-comment,user=octocat,sanitized=true]"

getAllTestCases()

function getAllTestCases(): readonly SafetyTestCase & {
  categoryId: SafetyCategoryIdType;
}[];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-categories.ts:123

Get all test cases across all categories.

Returns

readonly SafetyTestCase & { categoryId: SafetyCategoryIdType; }[]

Array of all test cases with their category IDs

getBuiltInAstRulesPath()

function getBuiltInAstRulesPath(): string;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:178

Resolve the built-in ast-rules/ directory, handling both dev (unbundled, src/security/ast-rule-runner.ts) and published (bundled, dist/index.js + dist/security/ast-rules/*.yml copied by tsup’s onSuccess step) layouts — the same two-layout problem getBuiltInTemplatesPath solves for workflow templates.

Returns

string

getCategoriesByMinRiskLevel()

function getCategoriesByMinRiskLevel(minLevel): readonly SafetyCategory[];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-categories.ts:107

Get all categories at or above a given risk level.

Parameters

minLevel

RiskLevelType

Minimum risk level to include

Returns

readonly SafetyCategory[]

Array of categories matching the risk level criteria

getCorroborationRules()

function getCorroborationRules(actionType): readonly CorroborationRule[];

Defined in: packages/nexus-agents/src/security/corroboration-validator.ts:281

Get the corroboration rules for an action type. Useful for displaying requirements to users. If the action type is unlisted, returns the strict Tier 1 floor rules.

Parameters

actionType

Returns

readonly CorroborationRule[]

getPolicy()

function getPolicy(id): SandboxPolicy | undefined;

Defined in: packages/nexus-agents/src/security/sandbox/default-policies.ts:150

Get a policy by ID.

Parameters

id

string

Returns

SandboxPolicy | undefined

getRequiredTrustTier()

function getRequiredTrustTier(actionType): "1" | "2" | "3" | "4";

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:163

Returns the minimum trust tier required for a given action type. Actions that modify state require higher trust.

Parameters

actionType

string

Returns

"1" | "2" | "3" | "4"

getSafetyCategory()

function getSafetyCategory(id): SafetyCategory | undefined;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-categories.ts:98

Get a safety category by ID.

Parameters

id

SafetyCategoryIdType

Category identifier

Returns

SafetyCategory | undefined

The category definition or undefined if not found

getSafetyTaxonomySummary()

function getSafetyTaxonomySummary(): SafetyTaxonomySummary;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-categories.ts:191

Get summary statistics for the safety taxonomy.

Returns

SafetyTaxonomySummary

Summary statistics object

getTestCasesByTags()

function getTestCasesByTags(tags): readonly SafetyTestCase & {
  categoryId: SafetyCategoryIdType;
}[];

Defined in: packages/nexus-agents/src/security/safety-bench/safety-categories.ts:139

Get test cases filtered by tags.

Parameters

Returns

readonly SafetyTestCase & { categoryId: SafetyCategoryIdType; }[]

Array of matching test cases

isMutatingAction()

function isMutatingAction(actionType): boolean;

Defined in: packages/nexus-agents/src/security/action-schema.ts:310

Check whether an action type can modify GitHub state. Mutating actions always require human approval before execution.

Parameters

actionType

The action type discriminator value.

Returns

boolean

True if the action can modify state.

isReadOnlyAction()

function isReadOnlyAction(actionType): boolean;

Defined in: packages/nexus-agents/src/security/action-schema.ts:299

Check whether an action type is read-only (does not modify GitHub state).

Parameters

actionType

The action type discriminator value.

Returns

boolean

True if the action is read-only.

loadRules()

function loadRules(dir): Promise<{
  id: string;
  language: "python" | "go";
  message: string;
  rule: Record<string, unknown>;
  severity: "error" | "info" | "warning";
}[]>;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:130

Load and Zod-validate every *.yml rule file in dir. FAILS CLOSED: a single malformed YAML file, or a file with an unrecognized language or missing field, throws a ValidationError — there is no “load what parsed, skip the rest” partial mode.

Parameters

dir

string

Returns

Promise<{ id: string; language: "python" | "go"; message: string; rule: Record<string, unknown>; severity: "error" | "info" | "warning"; }[]>

mapAuthorAssociation()

function mapAuthorAssociation(association): 
  | "unknown"
  | "owner"
  | "maintainer"
  | "collaborator"
  | "contributor"
  | "member";

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:24

Maps GitHub API author_association values to our GitHubUserRole enum. See: https://docs.github.com/en/graphql/reference/enums#commentauthorassociation

Parameters

association

string

Returns

parseATL()

function parseATL(atl): 
  | {
  rep?: number;
  sanitized: boolean;
  source: string;
  tier: "1" | "2" | "3" | "4";
  user: string;
}
  | undefined;

Defined in: packages/nexus-agents/src/security/firewall/agent-trust-labels.ts:49

Parses an ATL string back into structured data. Returns undefined if the string is not a valid ATL.

Parameters

atl

string

Returns

| { rep?: number; sanitized: boolean; source: string; tier: "1" | "2" | "3" | "4"; user: string; } | undefined

requiresCitation()

function requiresCitation(actionType): boolean;

Defined in: packages/nexus-agents/src/security/action-schema.ts:362

Check whether an action type requires at least one source citation. Escalation (RequestHumanApproval) and refusal (RefuseAction) are exempt.

Parameters

actionType

The action type discriminator value.

Returns

boolean

True if the action must include source citations.

requiresCorroboration()

function requiresCorroboration(tier): boolean;

Defined in: packages/nexus-agents/src/security/trust-classifier.ts:155

Checks whether a trust tier requires corroboration with Tier 1 sources. Tier 2 requires corroboration; Tier 1 is self-sufficient.

Parameters

tier

"1" | "2" | "3" | "4"

Returns

boolean

requiresHumanApproval()

function requiresHumanApproval(actionType): boolean;

Defined in: packages/nexus-agents/src/security/action-schema.ts:351

Whether an action needs human approval even after passing every policy check.

Distinct from isMutatingAction, which stays broad because it also drives the untrusted-input influence block — low-trust input must not be able to drive ANY mutating action, approved or not.

Parameters

actionType

The action type discriminator value.

Returns

boolean

True if a human must approve before execution.

resolveFirewallPolicyMode()

function resolveFirewallPolicyMode(env?, logger?): "audit" | "off" | "enforce";

Defined in: packages/nexus-agents/src/security/firewall/firewall-policy-mode.ts:73

Resolve the firewall policy mode from the environment.

Never throws, because a security layer must not fail-closed at startup on an operator typo (#3130). The two non-happy paths resolve DIFFERENTLY, though: unset or empty resolves silently to off (absence is the normal state), while an explicit-but-invalid value resolves to audit and emits one warn.

Parameters

env?

ProcessEnv = process.env

Environment to read (injectable for tests).

logger?

ILogger

Injectable for tests; defaults to the shared module logger.

Returns

"audit" | "off" | "enforce"

resolveReputationGatingMode()

function resolveReputationGatingMode(env?): "audit" | "off" | "enforce";

Defined in: packages/nexus-agents/src/security/reputation-model.ts:430

Resolve the gating mode from the environment (invalid → default + warn, never throws — #3130). Delegates to the shared resolveEnvMode so this flag and NEXUS_FIREWALL_POLICY coerce identically.

Parameters

env?

ProcessEnv = process.env

Returns

"audit" | "off" | "enforce"

runAstQaRules()

function runAstQaRules(opts): Promise<AstRuleFinding[]>;

Defined in: packages/nexus-agents/src/security/ast-rule-runner.ts:488

Run the polyglot QA/security ast-grep rules and return the capped findings array. Overflow beyond limit is counted and logged (never silently dropped) — use collectAstQaFindings directly when the caller needs the true total/overflow count programmatically.

Parameters

opts

RunAstQaRulesOptions

Returns

Promise<AstRuleFinding[]>

sanitizeInput()

function sanitizeInput(
   content, 
   userRole, 
   username, 
   config?
): {
  content: string;
  contentTierMeasured?: boolean;
  injectionFlags: (
     | "authority_claim"
     | "instruction_pattern"
     | "system_prompt_manipulation"
     | "hidden_content"
     | "urgency_manipulation"
     | "fake_conversation"
     | "base64_encoded"
    | "external_link_instruction")[];
  originalLength: number;
  sanitizationIncomplete?: boolean;
  sanitizedAt: string;
  strippedElements: {
     length: number;
     reason: string;
     startIndex: number;
     tag: string;
  }[];
  truncated?: boolean;
  trustTier: "1" | "2" | "3" | "4";
  userRole:   | "unknown"
     | "owner"
     | "maintainer"
     | "collaborator"
     | "contributor"
     | "member";
  wasModified: boolean;
};

Defined in: packages/nexus-agents/src/security/input-sanitizer.ts:428

Sanitizes untrusted GitHub input through the full Layer 1 pipeline:

HTML stripping (picture/source/img tags)
XML tag stripping (system/human/assistant)
HTML comment stripping (instruction-bearing comments only)
Injection pattern detection
Trust tier assignment

⚠ Use HostileInputFirewall.process() in agent code paths. Calling sanitizeInput() directly only runs Layer 1 — it does not evaluate the Rule of Two and does not emit audit-trail events. An agent that processes untrusted input while holding both write access and secrets violates the Rule of Two; evaluatePolicy in policy-gate.ts enforces that per action, and the firewall evaluates it per input as a signal (refusing only under NEXUS_FIREWALL_POLICY=enforce). The live paths route their trust decision through the firewall as of #4992 and keep direct sanitizeInput() calls only for content cleaning of text they embed. Direct use of this function is appropriate for unit tests and pure content analysis, not for agent decision paths.

Parameters

content

string

Raw untrusted content from GitHub

userRole

GitHub user’s relationship to the repository

username

string

GitHub username (for allowlist check)

config?

Partial<{ allowlistedMaintainers: string[]; failOpen: boolean; maxInputLength: number; }>

Optional sanitizer configuration

Returns

SanitizedInput with cleaned content and audit data

content

content: string;

Sanitized content with dangerous elements removed.

contentTierMeasured?

optional contentTierMeasured?: boolean;

injectionFlags

injectionFlags: (
  | "authority_claim"
  | "instruction_pattern"
  | "system_prompt_manipulation"
  | "hidden_content"
  | "urgency_manipulation"
  | "fake_conversation"
  | "base64_encoded"
  | "external_link_instruction")[];

Injection patterns detected in content.

originalLength

originalLength: number;

Original content before sanitization (for audit).

sanitizationIncomplete?

optional sanitizationIncomplete?: boolean;

True when a strip loop exhausted its pass budget with its own pattern still matching — i.e. content still carries markup the sanitizer removes.

sanitizedAt

sanitizedAt: string;

Timestamp of sanitization (ISO 8601).

strippedElements

strippedElements: {
  length: number;
  reason: string;
  startIndex: number;
  tag: string;
}[];

Elements stripped during sanitization (audit trail).

truncated?

optional truncated?: boolean;

Whether content exceeded the configured limit. Absent on records that predate this field.

trustTier

trustTier: "1" | "2" | "3" | "4" = TrustTierSchema;

Assigned trust tier based on user role and content analysis.

Deprecation note: required today; a future major makes it absent when unmeasured (see the next-major issue named in the changeset).

userRole

userRole: 
  | "unknown"
  | "owner"
  | "maintainer"
  | "collaborator"
  | "contributor"
  | "member" = GitHubUserRoleSchema;

GitHub user role of the input source.

wasModified

wasModified: boolean;

Whether any dangerous content was detected and stripped.

See

packages/nexus-agents/src/security/firewall/firewall-pipeline.ts
packages/nexus-agents/src/security/policy-gate.ts

validateAgentAction()

function validateAgentAction(input): ActionValidationResult;

Defined in: packages/nexus-agents/src/security/action-schema.ts:284

Validate an unknown value against the AgentActionSchema. Returns a Result: { ok: true; value } on success or { ok: false; error } on failure.

Parameters

input

unknown

The value to validate (typically parsed JSON from an agent).

Returns

ActionValidationResult

Validation result following the project Result pattern.

validateCommand()

function validateCommand(command, allowedCommands): PolicyViolation | null;

Defined in: packages/nexus-agents/src/security/sandbox/command-allowlist.ts:108

Validates a command name against the allowlist.

Parameters

command

string

allowedCommands

readonly string[]

Returns

PolicyViolation | null

validateCorroboration()

function validateCorroboration(action): CorroborationResult;

Defined in: packages/nexus-agents/src/security/corroboration-validator.ts:233

Validate that an agent action has sufficient corroboration from authoritative sources.

Parameters

action

The validated AgentAction to check.

Returns

CorroborationResult

CorroborationResult indicating whether requirements are met.

validateEvaluationCriterion()

function validateEvaluationCriterion(criterion): ZodSafeParseResult<{
  categories?: readonly string[];
  description: string;
  id: string;
  name: string;
  passThreshold?: number;
  type: "binary" | "threshold" | "scaled" | "categorical";
  weight: number;
}>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-categories.ts:177

Validate an evaluation criterion definition.

Parameters

criterion

unknown

Criterion to validate

Returns

ZodSafeParseResult<{ categories?: readonly string[]; description: string; id: string; name: string; passThreshold?: number; type: "binary" | "threshold" | "scaled" | "categorical"; weight: number; }>

Validation result with inferred schema type

validateSafetyCategory()

function validateSafetyCategory(category): ZodSafeParseResult<{
  criteria: readonly {
     categories?: readonly string[];
     description: string;
     id: string;
     name: string;
     passThreshold?: number;
     type: "binary" | "threshold" | "scaled" | "categorical";
     weight: number;
  }[];
  defaultRiskLevel: "critical" | "high" | "low" | "medium";
  description: string;
  exampleTestCases: readonly {
     context?: string;
     description: string;
     expectedOutcome: "escalate" | "refuse" | "caution" | "clarify" | "proceed" | "detect";
     id: string;
     input: string;
     name: string;
     riskLevel: "critical" | "high" | "low" | "medium";
     tags: readonly string[];
  }[];
  failureModes: readonly string[];
  id:   | "harm_physical"
     | "harm_emotional"
     | "harm_financial"
     | "deception"
     | "bias"
     | "privacy"
     | "manipulation"
     | "instruction_safety"
     | "robustness"
     | "risk_awareness";
  mitigationStrategies: readonly string[];
  name: string;
  parentId?:   | "harm_physical"
     | "harm_emotional"
     | "harm_financial"
     | "deception"
     | "bias"
     | "privacy"
     | "manipulation"
     | "instruction_safety"
     | "robustness"
     | "risk_awareness";
}>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-categories.ts:155

Validate a safety category definition.

Parameters

Returns

ZodSafeParseResult<{ criteria: readonly { categories?: readonly string[]; description: string; id: string; name: string; passThreshold?: number; type: "binary" | "threshold" | "scaled" | "categorical"; weight: number; }[]; defaultRiskLevel: "critical" | "high" | "low" | "medium"; description: string; exampleTestCases: readonly { context?: string; description: string; expectedOutcome: "escalate" | "refuse" | "caution" | "clarify" | "proceed" | "detect"; id: string; input: string; name: string; riskLevel: "critical" | "high" | "low" | "medium"; tags: readonly string[]; }[]; failureModes: readonly string[]; id: | "harm_physical" | "harm_emotional" | "harm_financial" | "deception" | "bias" | "privacy" | "manipulation" | "instruction_safety" | "robustness" | "risk_awareness"; mitigationStrategies: readonly string[]; name: string; parentId?: | "harm_physical" | "harm_emotional" | "harm_financial" | "deception" | "bias" | "privacy" | "manipulation" | "instruction_safety" | "robustness" | "risk_awareness"; }>

Validation result with inferred schema type

validateTestCase()

function validateTestCase(testCase): ZodSafeParseResult<{
  context?: string;
  description: string;
  expectedOutcome: "escalate" | "refuse" | "caution" | "clarify" | "proceed" | "detect";
  id: string;
  input: string;
  name: string;
  riskLevel: "critical" | "high" | "low" | "medium";
  tags: readonly string[];
}>;

Defined in: packages/nexus-agents/src/security/safety-bench/safety-categories.ts:166

Validate a test case definition.

Parameters

testCase

unknown

Test case to validate

Returns

ZodSafeParseResult<{ context?: string; description: string; expectedOutcome: "escalate" | "refuse" | "caution" | "clarify" | "proceed" | "detect"; id: string; input: string; name: string; riskLevel: "critical" | "high" | "low" | "medium"; tags: readonly string[]; }>

Validation result with inferred schema type