open/llm-security
1
0
Fork 0
Code Issues Releases 1 Activity

feat(llm-security)!: v8 Phase 3 step 1 - remove the deprecated mode env-vars

Browse source 
BREAKING CHANGE: the four LLM_SECURITY_* configuration env-vars deprecated in
v7.3.0 are removed. .llm-security/policy.json is now the only source:

  LLM_SECURITY_INJECTION_MODE     -> injection.mode
  LLM_SECURITY_TRIFECTA_MODE      -> trifecta.mode
  LLM_SECURITY_ESCALATION_WINDOW  -> trifecta.escalation_window
  LLM_SECURITY_AUDIT_LOG          -> audit.log_path
  LLM_SECURITY_DEPRECATION_QUIET  -> dies with the mechanism it silenced

Setting a removed var is now inert - it does not warn, and it does not
configure. Env-vars with no policy equivalent (PRECOMPACT_MODE,
PRECOMPACT_MAX_BYTES, UPDATE_CHECK, MCP_CACHE_FILE, IDE_ROOTS) are unaffected.

getPolicyValueWithEnvWarn and its one-shot stderr warning are deleted from
policy-loader.mjs, along with the module-scoped warned-var Set. The four call
sites collapse to getPolicyValue. getPolicyValue's JSDoc claimed "environment
variables ALWAYS take precedence" - it never read env itself, so that line
described the shim, and it is corrected rather than deleted.

User-facing hook strings that advertised a removed var as the escape hatch now
name the policy key instead: the inject-scan block reason, its warn-mode note,
both escalation-window advisories, and the trifecta block message. A blocked
user following the old text would have set a var that does nothing.

Tests. tests/lib/v8-env-removal.test.mjs is the regression gate and was written
failing first (8 of 12 red before the change). It pins the NEGATIVE - setting a
removed var does not alter the outcome - because that is the half that rots
silently: a re-introduced process.env read would leave every migrated positive
test green, since those configure through policy.json and never set the var at
all. One assertion walks hooks/scripts and scanners for `process.env.<removed>`
so the re-introduction is caught structurally, not only behaviourally.

The 44 env-driven test occurrences (18 inject-scan, 13+4 session-guard, 9
audit-trail) migrate to a throwaway .llm-security/policy.json via a new
runHookWithPolicy helper in hook-helper.mjs; audit-trail runs in-process, so it
supplies the same policy through CLAUDE_PROJECT_ROOT. The D3 mechanism tests in
policy-loader.test.mjs are deleted with the mechanism.

Suite 2039 tests, 2037 pass (+12 gate, -7 D3 mechanism). The 2 failures are the
known parallel-load timing flakes (pre-compact-scan size-cap,
pre-install-supply-chain F-3); both green when run isolated.

Remaining in Phase 3: posture-scanner TRIFECTA_MODE heuristic, riskScoreV1
removal, ghost-var cleanup, docs + migration note.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BB4vXvwvtW4dxbPRd6vsez
This commit is contained in:
Kjell Tore Guttormsen 2026-08-09 10:17:47 +02:00
commit b6af9b46df
10 changed files with 430 additions and 299 deletions
Download patch file Download diff file Expand all files Collapse all files

38
hooks/scripts/post-session-guard.mjs
View file

@ -12,8 +12,9 @@
//
// Rule of Two (Meta, Oct 2025):
// Of 3 capabilities A (untrusted input), B (sensitive data), C (state change/exfil),
// an agent should NEVER hold all 3 simultaneously. Env var LLM_SECURITY_TRIFECTA_MODE
// controls enforcement: warn (default), block (exit 2 for high-confidence trifecta), off.
// an agent should NEVER hold all 3 simultaneously. The policy.json key
// `trifecta.mode` controls enforcement: warn (default), block (exit 2 for
// high-confidence trifecta), off.
//
// Long-horizon monitoring (OpenAI Atlas, Dec 2025):
// 100-call window alongside 20-call for slow-burn trifecta detection and
@ -43,7 +44,7 @@ import { createHash } from 'node:crypto';
import { extractMcpServer } from '../../scanners/lib/mcp-description-cache.mjs';
import { jensenShannonDivergence, buildDistribution } from '../../scanners/lib/distribution-stats.mjs';
import { writeAuditEvent } from '../../scanners/lib/audit-trail.mjs';
import { getPolicyValue, getPolicyValueWithEnvWarn } from '../../scanners/lib/policy-loader.mjs';
import { getPolicyValue } from '../../scanners/lib/policy-loader.mjs';
// ---------------------------------------------------------------------------
// Constants
@ -61,28 +62,25 @@ const DRIFT_THRESHOLD = 0.25;
const DRIFT_SAMPLE_SIZE = 20;
// Sub-agent delegation tracking (DeepMind Agent Traps kat. 4, v5.0 S4)
// E17 (v7.2.0): primary window configurable via LLM_SECURITY_ESCALATION_WINDOW
// (default 5). Secondary 20-call window emits MEDIUM advisory for delegation
// in the [primary, 20]-call range. Both reference an input_source; the
// secondary catches slow-burn variants where the attacker waits past the
// primary window before delegating.
// D3 (v7.3.0): env-var path emits a v8.0.0 deprecation warning when
// trifecta.escalation_window is also set in policy.json.
// E17 (v7.2.0): primary window configurable via the policy.json key
// `trifecta.escalation_window` (default 5). Secondary 20-call window emits
// MEDIUM advisory for delegation in the [primary, 20]-call range. Both
// reference an input_source; the secondary catches slow-burn variants where
// the attacker waits past the primary window before delegating.
// v8.0.0: the LLM_SECURITY_ESCALATION_WINDOW env-var was removed.
const DELEGATION_ESCALATION_WINDOW = (() => {
const resolved = getPolicyValueWithEnvWarn(
'trifecta', 'escalation_window', 'LLM_SECURITY_ESCALATION_WINDOW', 5
);
const resolved = getPolicyValue('trifecta', 'escalation_window', 5);
// policy.json is user-authored, so a quoted "3" is a realistic mistake.
const parsed = typeof resolved === 'string' ? parseInt(resolved, 10) : resolved;
if (Number.isFinite(parsed) && parsed > 0) return parsed;
return 5;
})();
const DELEGATION_ESCALATION_WINDOW_MEDIUM = 20; // secondary longer-window advisory
// Rule of Two enforcement mode: block | warn | off (env var takes precedence over policy).
// D3 (v7.3.0): env-var path emits a v8.0.0 deprecation warning when
// trifecta.mode is also set in policy.json.
// Rule of Two enforcement mode: block | warn | off, from policy.json
// `trifecta.mode`. v8.0.0: the LLM_SECURITY_TRIFECTA_MODE env-var was removed.
const TRIFECTA_MODE = String(
getPolicyValueWithEnvWarn('trifecta', 'mode', 'LLM_SECURITY_TRIFECTA_MODE', 'warn')
getPolicyValue('trifecta', 'mode', 'warn')
).toLowerCase();
// Volume tracking thresholds (cumulative bytes per session)
@ -570,7 +568,7 @@ function formatEscalationWarning(delegationDetail, inputDetail, tier = 'primary'
'catches attackers who deliberately wait past the primary window before delegating,\n' +
'and surfaces patterns that the primary 5-call window cannot. Review whether this\n' +
'delegation is expected and appropriately scoped.\n' +
'Configure window via LLM_SECURITY_ESCALATION_WINDOW env var (default 5).'
'Configure window via the trifecta.escalation_window key in .llm-security/policy.json (default 5).'
);
}
return (
@ -583,7 +581,7 @@ function formatEscalationWarning(delegationDetail, inputDetail, tier = 'primary'
'to spawn sub-agents with capabilities beyond the original task scope.\n' +
'This is a known attack vector (DeepMind AI Agent Traps, Category 4).\n' +
'Review whether this delegation is expected and appropriately scoped.\n' +
'Configure window via LLM_SECURITY_ESCALATION_WINDOW env var (default 5).'
'Configure window via the trifecta.escalation_window key in .llm-security/policy.json (default 5).'
);
}
@ -929,7 +927,7 @@ if (!(classes.length === 1 && (classes[0] === 'neutral' || classes[0] === 'deleg
process.stderr.write(
'BLOCKED: Rule of Two violation — lethal trifecta detected.\n' +
context +
' Set LLM_SECURITY_TRIFECTA_MODE=warn to downgrade to advisory.\n'
' Set "trifecta": {"mode": "warn"} in .llm-security/policy.json to downgrade to advisory.\n'
);
process.stdout.write(JSON.stringify({ decision: 'block' }));
process.exit(2);