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

17
scanners/lib/audit-trail.mjs
View file

@ -1,12 +1,12 @@
// audit-trail.mjs — Structured JSONL audit trail writer
// Resolves the audit-log path via getPolicyValueWithEnvWarn so the env-var
// LLM_SECURITY_AUDIT_LOG and policy.json key audit.log_path stay in sync,
// with a one-time deprecation warning when both are explicitly set.
// No-op when neither env nor policy provides a path. Zero external dependencies.
// Resolves the audit-log path from the policy.json key `audit.log_path`.
// v8.0.0: the LLM_SECURITY_AUDIT_LOG env-var was removed after its v7.3.0
// deprecation runway; policy.json is now the only source.
// No-op when policy provides no path. Zero external dependencies.
import { appendFileSync, writeFileSync, accessSync, constants } from 'node:fs';
import { dirname } from 'node:path';
import { getPolicyValueWithEnvWarn } from './policy-loader.mjs';
import { getPolicyValue } from './policy-loader.mjs';
let auditPath = null;
let initialized = false;
@ -19,10 +19,7 @@ function initAuditTrail() {
if (initialized) return auditPath !== null;
initialized = true;
// D3 (v7.3.0): env still wins, deprecation warning when policy also set.
const resolved = getPolicyValueWithEnvWarn(
'audit', 'log_path', 'LLM_SECURITY_AUDIT_LOG', null
);
const resolved = getPolicyValue('audit', 'log_path', null);
if (!resolved) return false;
try {
@ -41,7 +38,7 @@ function initAuditTrail() {
/**
* Write a structured audit event as one JSON line.
* No-op when LLM_SECURITY_AUDIT_LOG is not set.
* No-op when the policy.json key audit.log_path is not set.
*
* @param {object} event
* @param {string} event.event_type - e.g. trifecta_warning, injection_detected

66
scanners/lib/policy-loader.mjs
View file

@ -101,11 +101,6 @@ const DEFAULT_POLICY = Object.freeze({
// Cache loaded policy per project root
const cache = new Map();
// Module-scoped Set of env-var names already warned about — dedupes to one
// stderr line per env-var per process, regardless of how many call-sites
// invoke getPolicyValueWithEnvWarn for the same name.
const _warnedEnvVars = new Set();
/**
* Resolve project root from env or cwd.
* @param {string} [explicitRoot]
@ -170,7 +165,12 @@ export function loadPolicy(projectRoot) {
/**
* Get a specific policy value with fallback.
* Environment variables ALWAYS take precedence over policy file values.
*
* v8.0.0: `.llm-security/policy.json` is the only configuration source for
* these keys. The `LLM_SECURITY_*` mode env-vars that used to take precedence
* were removed with the v7.3.0 deprecation runway — see the migration table in
* README.md. Note that this function has never read env itself; the override
* lived in the now-deleted `getPolicyValueWithEnvWarn` shim.
*
* @param {string} section - Policy section (e.g. 'injection', 'trifecta')
* @param {string} key - Key within section (e.g. 'mode', 'window_size')
@ -188,57 +188,6 @@ export function getPolicyValue(section, key, defaultValue, projectRoot) {
return defaultValue;
}
/**
* Resolve a policy value with an overlapping env-var, emitting a one-time
* stderr deprecation warning when both the env-var AND the policy.json key
* are explicitly set.
*
* Resolution order (env-wins is unchanged from getPolicyValue contract):
* 1. If LLM_SECURITY_DEPRECATION_QUIET=1, suppress warning logic entirely
* and return env-value (if defined) else policy-value.
* 2. Otherwise, if env-var is set AND policy-value differs from
* defaultValue (heuristic: user wrote the key in policy.json),
* emit one stderr warning per envVarName per process.
* 3. Return env-value if defined, else policy-value.
*
* Why "differs from defaultValue" rather than parsing the raw policy file:
* loadPolicy() deep-merges DEFAULT_POLICY so `key in policy[section]` is
* always true. Comparing the resolved value to the caller's defaultValue
* is a reliable proxy for "user explicitly overrode this in policy.json"
* because callers pass defaults that match DEFAULT_POLICY.
*
* @param {string} section - Policy section (e.g. 'injection', 'trifecta')
* @param {string} key - Key within section (e.g. 'mode')
* @param {string} envVarName - Overlapping env-var (e.g. 'LLM_SECURITY_INJECTION_MODE')
* @param {*} defaultValue - Hardcoded default (must match DEFAULT_POLICY value)
* @param {string} [projectRoot] - Explicit root
* @returns {*}
*/
export function getPolicyValueWithEnvWarn(section, key, envVarName, defaultValue, projectRoot) {
const envValue = process.env[envVarName];
if (process.env.LLM_SECURITY_DEPRECATION_QUIET === '1') {
if (envValue !== undefined) return envValue;
return getPolicyValue(section, key, defaultValue, projectRoot);
}
const policyValue = getPolicyValue(section, key, defaultValue, projectRoot);
if (envValue !== undefined && policyValue !== defaultValue) {
if (!_warnedEnvVars.has(envVarName)) {
_warnedEnvVars.add(envVarName);
process.stderr.write(
`[llm-security] Deprecation: env-var ${envVarName} will be removed in v8.0.0; ` +
`policy.json key ${section}.${key} also set — env wins for now. ` +
`Suppress with LLM_SECURITY_DEPRECATION_QUIET=1.\n`
);
}
}
if (envValue !== undefined) return envValue;
return policyValue;
}
/**
* Get the full default policy (for documentation/example generation).
* @returns {object}
@ -248,9 +197,8 @@ export function getDefaultPolicy() {
}
/**
* Reset cache and warning dedup state (for testing only).
* Reset the per-root policy cache (for testing only).
*/
export function _resetCacheForTest() {
cache.clear();
_warnedEnvVars.clear();
}