lintai docs

Appearance

Rule Reference

SEC361lintai-ai-securitypreviewclaude_settingswarn

Claude settings: missing `$schema`

Claude settings file is missing a top-level `$schema` reference

Provider
lintai-ai-security
Surface
claude_settings
Scope
per_file
Tier
preview
Severity
warn
Confidence
high
Detection
structural
Remediation
message_only

Activation Model

Preset Membership

This rule is part of the builtin activation graph through these preset memberships.

previewmembership
claudemembership

Lifecycle

Stable Lifecycle Contract

State

stable_gated

Graduation rationale

Checks shared committed Claude settings for omission of a top-level `$schema` reference.

Deterministic signal basis

ClaudeSettingsSignals exact top-level `$schema` presence detection in parsed Claude settings JSON.

Malicious corpus
claude-settings-missing-schema
Benign corpus
claude-settings-schema-present-safe
structured evidence required remediation reviewed
Canonical note

Structural preview rule; deterministic today, but the preview contract may still evolve.

Nearby Signals

Related Rules

SEC363Claude settings: home-directory hook pathClaude settings hook command uses a home-directory path in a shared committed configclaude_settingspreview
SEC365Claude settings: non-HTTPS allowed HTTP hook URLClaude settings allow non-HTTPS HTTP hook URLs in a shared committed configclaude_settingspreview
SEC366Claude settings: dangerous HTTP hook host literalClaude settings allow dangerous host literals in `allowedHttpHookUrls`claude_settingspreview
SEC368Claude settings: repo-external absolute hook pathClaude settings hook command uses a repo-external absolute path in a shared committed configclaude_settingspreview
SEC381Claude settings: command hook missing `timeout`Claude settings command hook should set `timeout` in a shared committed configclaude_settingspreview
SEC382Claude settings: `matcher` on unsupported hook eventClaude settings should not use `matcher` on unsupported hook eventsclaude_settingspreview

Why It Matters ​

SEC361 flags committed Claude settings files that omit a top-level $schema reference.

This is useful because:

  • shared .claude/settings.json files are configuration artifacts, not free-form notes
  • a schema reference improves editor validation and makes team-owned settings easier to review
  • the failure mode is community-hostile: the file looks authoritative, but misses a low-cost interoperability hint that many users expect in checked-in JSON config

What Triggers ​

This rule applies only to committed Claude settings surfaces:

  • .claude/settings.json
  • claude/settings.json

It triggers when:

  • the JSON parses as a top-level object
  • and the object does not contain $schema

Example that triggers:

json
{
  "hooks": {
    "Stop": []
  }
}

Example that stays clean:

json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "hooks": {
    "Stop": []
  }
}
  • fixture-like paths under tests/, fixtures/, examples/, or samples/

False Positives ​

This rule stays Preview because some repositories intentionally keep Claude settings minimal or target editor setups without schema-aware validation. The signal is about deterministic configuration quality and maintainability, not about exploitability.

Remediation ​

Add the top-level SchemaStore URL:

json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

Keep the rest of the settings file unchanged. The goal is to make shared Claude settings easier to validate and review, not to change runtime behavior.