Kjell Tore Guttormsen
3633571c7e
settings-validator now validates the autoMode block (auto-mode classifier
config). Structure (medium): autoMode must be an object whose only keys are
environment/allow/soft_deny/hard_deny, each a string array ("$defaults" is a
valid entry); flags not-an-object, unknown-subkey, not-string-array. Dead-config
(low): Claude Code does not read autoMode from shared project settings
(.claude/settings.json), so an autoMode block committed there has no effect —
keyed on file.scope === 'project'.
Both premises primary-source-verified (code.claude.com/docs/en/auto-mode-config).
The plan's "test per-file scope first" gate passed: ConfigFile already carries
scope. SET is in the orchestrator; SC-5 re-checked, byte-equal (snapshot fixture
has no autoMode). Fixtures force-added (.claude/ is gitignored).
Tests +5 (944->949). Scanner count unchanged (13). --json/--raw byte-stable.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ter3E2JSi1Khgmuf2kady8
329 lines
14 KiB
JavaScript
329 lines
14 KiB
JavaScript
/**
|
|
* SET Scanner — Settings.json Validator
|
|
* Validates schema, detects unknown/deprecated keys, type mismatches.
|
|
* Finding IDs: CA-SET-NNN
|
|
*/
|
|
|
|
import { readTextFile } from './lib/file-discovery.mjs';
|
|
import { finding, scannerResult } from './lib/output.mjs';
|
|
import { SEVERITY } from './lib/severity.mjs';
|
|
import { parseJson } from './lib/yaml-parser.mjs';
|
|
import { extractKeys } from './lib/string-utils.mjs';
|
|
|
|
const SCANNER = 'SET';
|
|
|
|
/** Known top-level settings.json keys (as of CC 2.1.181 / June 2026) */
|
|
const KNOWN_KEYS = new Set([
|
|
'additionalDirectories',
|
|
'agent', 'allowAllClaudeAiMcps', 'allowedChannelPlugins', 'allowedHttpHookUrls',
|
|
'allowedMcpServers', 'allowManagedHooksOnly', 'allowManagedMcpServersOnly',
|
|
'allowManagedPermissionRulesOnly', 'alwaysThinkingEnabled', 'apiKeyHelper',
|
|
'attribution', 'autoMemoryDirectory', 'autoMemoryEnabled', 'autoMode',
|
|
'autoUpdatesChannel', 'availableModels', 'awsAuthRefresh', 'awsCredentialExport',
|
|
'blockedMarketplaces', 'channelsEnabled', 'cleanupPeriodDays', 'claudeMdExcludes',
|
|
'companyAnnouncements', 'defaultShell', 'deniedMcpServers', 'disableAllHooks',
|
|
'disableAutoMode', 'disableBundledSkills', 'disableDeepLinkRegistration',
|
|
'disabledMcpjsonServers', 'effortLevel', 'enableAllProjectMcpServers',
|
|
'enabledMcpjsonServers', 'enabledPlugins', 'enforceAvailableModels', 'env',
|
|
'extraKnownMarketplaces', 'fallbackModel', 'fastModePerSessionOptIn',
|
|
'feedbackSurveyRate', 'fileSuggestion', 'footerLinksRegexes', 'forceLoginMethod',
|
|
'forceLoginOrgUUID', 'hooks', 'httpHookAllowedEnvVars', 'includeCoAuthoredBy',
|
|
'includeGitInstructions', 'language', 'model', 'modelOverrides', 'otelHeadersHelper',
|
|
'outputStyle', 'parentSettingsBehavior', 'permissions', 'plansDirectory',
|
|
'pluginSuggestionMarketplaces', 'pluginTrustMessage', 'prefersReducedMotion',
|
|
'requiredMaximumVersion', 'requiredMinimumVersion', 'respectGitignore', 'sandbox',
|
|
'showClearContextOnPlanAccept', 'showThinkingSummaries', 'skillOverrides',
|
|
'spinnerTipsEnabled',
|
|
'spinnerTipsOverride', 'spinnerVerbs', 'statusLine', 'strictKnownMarketplaces',
|
|
'useAutoModeDuringPlan', 'voiceEnabled', 'wheelScrollAccelerationEnabled',
|
|
'worktree', '$schema',
|
|
]);
|
|
|
|
/** Deprecated keys with migration info */
|
|
const DEPRECATED_KEYS = new Map([
|
|
['includeCoAuthoredBy', 'Use "attribution" instead'],
|
|
]);
|
|
|
|
/** Keys that require specific types */
|
|
const TYPE_CHECKS = new Map([
|
|
['alwaysThinkingEnabled', 'boolean'],
|
|
['autoMemoryEnabled', 'boolean'],
|
|
['channelsEnabled', 'boolean'],
|
|
['cleanupPeriodDays', 'number'],
|
|
['disableAllHooks', 'boolean'],
|
|
['disableBundledSkills', 'boolean'],
|
|
['effortLevel', 'string'],
|
|
['enableAllProjectMcpServers', 'boolean'],
|
|
['fastModePerSessionOptIn', 'boolean'],
|
|
['feedbackSurveyRate', 'number'],
|
|
['includeGitInstructions', 'boolean'],
|
|
['language', 'string'],
|
|
['model', 'string'],
|
|
['outputStyle', 'string'],
|
|
['prefersReducedMotion', 'boolean'],
|
|
['respectGitignore', 'boolean'],
|
|
['showThinkingSummaries', 'boolean'],
|
|
['spinnerTipsEnabled', 'boolean'],
|
|
['voiceEnabled', 'boolean'],
|
|
['wheelScrollAccelerationEnabled', 'boolean'],
|
|
]);
|
|
|
|
/** Valid effortLevel values (CC 2.1.154 added 'xhigh' as the Opus-4.8 top tier) */
|
|
const VALID_EFFORT_LEVELS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
|
|
|
|
/** v5 M6: warn when additionalDirectories grows beyond this — each entry adds
|
|
* a project root to walks/discovery, inflating per-turn cost and confusing scope. */
|
|
const ADDITIONAL_DIRS_THRESHOLD = 2;
|
|
|
|
/** The only valid sub-keys of `autoMode`, each a prose-rule string array
|
|
* (the literal "$defaults" is a valid entry). Verified against
|
|
* code.claude.com/docs/en/auto-mode-config. */
|
|
const AUTO_MODE_SUBKEYS = new Set(['environment', 'allow', 'soft_deny', 'hard_deny']);
|
|
|
|
/**
|
|
* Scan all settings.json files discovered.
|
|
* @param {string} targetPath
|
|
* @param {{ files: import('./lib/file-discovery.mjs').ConfigFile[] }} discovery
|
|
* @returns {Promise<object>}
|
|
*/
|
|
export async function scan(targetPath, discovery) {
|
|
const start = Date.now();
|
|
const settingsFiles = discovery.files.filter(f => f.type === 'settings-json');
|
|
const findings = [];
|
|
let filesScanned = 0;
|
|
|
|
if (settingsFiles.length === 0) {
|
|
return scannerResult(SCANNER, 'skipped', [], 0, Date.now() - start);
|
|
}
|
|
|
|
for (const file of settingsFiles) {
|
|
const content = await readTextFile(file.absPath);
|
|
if (!content) continue;
|
|
filesScanned++;
|
|
|
|
const parsed = parseJson(content);
|
|
if (parsed === null) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.critical,
|
|
title: 'Invalid JSON in settings file',
|
|
description: `${file.relPath} contains invalid JSON and will be ignored by Claude Code.`,
|
|
file: file.absPath,
|
|
recommendation: 'Fix JSON syntax errors. Use a JSON validator.',
|
|
autoFixable: false,
|
|
}));
|
|
continue;
|
|
}
|
|
|
|
// Check for unknown keys
|
|
for (const key of Object.keys(parsed)) {
|
|
if (!KNOWN_KEYS.has(key)) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.medium,
|
|
title: 'Unknown settings key',
|
|
description: `${file.relPath}: "${key}" is not a recognized settings.json key. It will be silently ignored.`,
|
|
file: file.absPath,
|
|
evidence: key,
|
|
recommendation: 'Check spelling. See https://json.schemastore.org/claude-code-settings.json for valid keys.',
|
|
autoFixable: false,
|
|
}));
|
|
}
|
|
}
|
|
|
|
// Check for deprecated keys
|
|
for (const [key, migration] of DEPRECATED_KEYS) {
|
|
if (parsed[key] !== undefined) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.medium,
|
|
title: 'Deprecated settings key',
|
|
description: `${file.relPath}: "${key}" is deprecated. ${migration}`,
|
|
file: file.absPath,
|
|
evidence: `${key}: ${JSON.stringify(parsed[key])}`,
|
|
recommendation: migration,
|
|
autoFixable: true,
|
|
}));
|
|
}
|
|
}
|
|
|
|
// Type validation
|
|
for (const [key, expectedType] of TYPE_CHECKS) {
|
|
if (parsed[key] !== undefined && typeof parsed[key] !== expectedType) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.high,
|
|
title: 'Type mismatch in settings',
|
|
description: `${file.relPath}: "${key}" should be ${expectedType}, got ${typeof parsed[key]}.`,
|
|
file: file.absPath,
|
|
evidence: `${key}: ${JSON.stringify(parsed[key])} (${typeof parsed[key]})`,
|
|
recommendation: `Change "${key}" to a ${expectedType} value.`,
|
|
autoFixable: true,
|
|
}));
|
|
}
|
|
}
|
|
|
|
// effortLevel value check
|
|
if (parsed.effortLevel && !VALID_EFFORT_LEVELS.has(parsed.effortLevel)) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.medium,
|
|
title: 'Invalid effortLevel value',
|
|
description: `${file.relPath}: effortLevel "${parsed.effortLevel}" is not valid.`,
|
|
file: file.absPath,
|
|
evidence: `effortLevel: "${parsed.effortLevel}"`,
|
|
recommendation: `Use one of: ${[...VALID_EFFORT_LEVELS].join(', ')}`,
|
|
autoFixable: true,
|
|
}));
|
|
}
|
|
|
|
// Missing $schema hint
|
|
if (!parsed.$schema) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.info,
|
|
title: 'Missing $schema reference',
|
|
description: `${file.relPath} lacks a $schema reference. Adding one enables autocomplete in VS Code/Cursor.`,
|
|
file: file.absPath,
|
|
recommendation: 'Add: "$schema": "https://json.schemastore.org/claude-code-settings.json"',
|
|
autoFixable: true,
|
|
}));
|
|
}
|
|
|
|
// Permissions checks
|
|
if (parsed.permissions) {
|
|
const perms = parsed.permissions;
|
|
|
|
if (!perms.deny || (Array.isArray(perms.deny) && perms.deny.length === 0)) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.medium,
|
|
title: 'No deny rules configured',
|
|
description: `${file.relPath}: No permission deny rules. Claude can access all files including .env and secrets.`,
|
|
file: file.absPath,
|
|
recommendation: 'Add deny rules for sensitive files: "deny": ["Read(./.env)", "Read(./secrets/**)"]',
|
|
autoFixable: false,
|
|
}));
|
|
}
|
|
|
|
if (!perms.allow || (Array.isArray(perms.allow) && perms.allow.length === 0)) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.low,
|
|
title: 'No allow rules configured',
|
|
description: `${file.relPath}: No permission allow rules. This means frequent permission prompts for common operations.`,
|
|
file: file.absPath,
|
|
recommendation: 'Add allow rules for common tools: "allow": ["Bash(npm run *)", "Read(src/**)"]',
|
|
autoFixable: false,
|
|
}));
|
|
}
|
|
}
|
|
|
|
// additionalDirectories threshold (v5 M6)
|
|
if (Array.isArray(parsed.additionalDirectories) &&
|
|
parsed.additionalDirectories.length > ADDITIONAL_DIRS_THRESHOLD) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.low,
|
|
title: 'Many additionalDirectories entries',
|
|
description:
|
|
`${file.relPath}: additionalDirectories has ${parsed.additionalDirectories.length} ` +
|
|
`entries (>${ADDITIONAL_DIRS_THRESHOLD}). Each entry expands Claude's read scope ` +
|
|
'across additional project roots, inflating discovery cost and risking unintended access.',
|
|
file: file.absPath,
|
|
evidence: parsed.additionalDirectories.slice(0, 5).map(d => `"${d}"`).join(', '),
|
|
recommendation:
|
|
'Trim to the minimum set needed. Prefer launching Claude from the relevant root ' +
|
|
'rather than chaining many directories.',
|
|
autoFixable: false,
|
|
}));
|
|
}
|
|
|
|
// autoMode validation (auto-mode classifier config).
|
|
// Structure: must be an object whose only keys are the four documented
|
|
// prose-rule arrays (each an array of strings; "$defaults" is a valid entry).
|
|
// Dead-config: Claude Code does NOT read autoMode from SHARED project settings
|
|
// (.claude/settings.json) — "a checked-in repo cannot inject its own allow
|
|
// rules" — so it is only honored in user/local/managed scopes.
|
|
if (parsed.autoMode !== undefined) {
|
|
const am = parsed.autoMode;
|
|
if (typeof am !== 'object' || am === null || Array.isArray(am)) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.medium,
|
|
title: 'autoMode must be an object',
|
|
description: `${file.relPath}: "autoMode" must be an object with environment/allow/soft_deny/hard_deny arrays, got ${Array.isArray(am) ? 'array' : typeof am}.`,
|
|
file: file.absPath,
|
|
evidence: `autoMode: ${JSON.stringify(am)}`,
|
|
recommendation: 'Set autoMode to an object, e.g. { "environment": ["$defaults"] }.',
|
|
autoFixable: false,
|
|
details: { key: 'autoMode', problem: 'not-an-object' },
|
|
}));
|
|
} else {
|
|
for (const subKey of Object.keys(am)) {
|
|
if (!AUTO_MODE_SUBKEYS.has(subKey)) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.medium,
|
|
title: `autoMode has an unknown sub-key: ${subKey}`,
|
|
description: `${file.relPath}: "autoMode.${subKey}" is not a recognized sub-key. Valid keys are environment, allow, soft_deny, hard_deny. It is silently ignored — a typo of a real key (e.g. "hard_denies") means those rules never apply.`,
|
|
file: file.absPath,
|
|
evidence: `autoMode.${subKey}`,
|
|
recommendation: 'Use only environment, allow, soft_deny, hard_deny. Check for typos.',
|
|
autoFixable: false,
|
|
details: { key: 'autoMode', subKey, problem: 'unknown-subkey' },
|
|
}));
|
|
continue;
|
|
}
|
|
const val = am[subKey];
|
|
const isStringArray = Array.isArray(val) && val.every(e => typeof e === 'string');
|
|
if (!isStringArray) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.medium,
|
|
title: `autoMode.${subKey} must be an array of strings`,
|
|
description: `${file.relPath}: "autoMode.${subKey}" must be an array of prose-rule strings (the literal "$defaults" is allowed), got ${Array.isArray(val) ? 'an array with a non-string entry' : typeof val}.`,
|
|
file: file.absPath,
|
|
evidence: `autoMode.${subKey}: ${JSON.stringify(val)}`,
|
|
recommendation: `Set "autoMode.${subKey}" to an array of strings, e.g. ["$defaults"].`,
|
|
autoFixable: false,
|
|
details: { key: 'autoMode', subKey, problem: 'not-string-array' },
|
|
}));
|
|
}
|
|
}
|
|
}
|
|
// Dead-config: shared project settings (.claude/settings.json) is not read.
|
|
if (file.scope === 'project') {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.low,
|
|
title: 'autoMode in shared project settings is ignored by Claude Code',
|
|
description: `${file.relPath}: Claude Code does not read "autoMode" from shared project settings (.claude/settings.json), so a checked-in repo cannot inject its own rules. This autoMode block has no effect where it is.`,
|
|
file: file.absPath,
|
|
evidence: 'autoMode in shared .claude/settings.json (project scope)',
|
|
recommendation: 'Move autoMode to user settings (~/.claude/settings.json), local settings (.claude/settings.local.json), or managed settings.',
|
|
autoFixable: false,
|
|
details: { key: 'autoMode', problem: 'shared-project-scope' },
|
|
}));
|
|
}
|
|
}
|
|
|
|
// hooks checks (basic — detailed in hook-validator)
|
|
if (parsed.hooks) {
|
|
if (Array.isArray(parsed.hooks)) {
|
|
findings.push(finding({
|
|
scanner: SCANNER,
|
|
severity: SEVERITY.critical,
|
|
title: 'Hooks configured as array instead of object',
|
|
description: `${file.relPath}: "hooks" must be an object with event keys, not an array. All hooks will be ignored.`,
|
|
file: file.absPath,
|
|
evidence: '"hooks": [...]',
|
|
recommendation: 'Change to object format: "hooks": { "PreToolUse": [...] }',
|
|
autoFixable: true,
|
|
}));
|
|
}
|
|
}
|
|
}
|
|
|
|
return scannerResult(SCANNER, 'ok', findings, filesScanned, Date.now() - start);
|
|
}
|