Skip to main content

Security Scanning

AI Primitives Hub includes a native static security scanner for Markdown-based AI artifacts such as prompts, instructions, agents, skills, hooks, and supported Claude configuration files.

The scanner looks for suspicious content and unsafe configuration patterns. It does not execute files, call an LLM, access the network, or replace human security review.

Quick start​

From an AI Primitives Hub or primitive source repository:

ai-primitives-hub security scan

Scan selected files or directories:

ai-primitives-hub security scan skills/ agents/reviewer/SKILL.md

The default directory scan:

  • recursively considers .md and .markdown files;
  • skips .git and node_modules;
  • skips README.md and CHANGELOG.md unless --include-doc-files is used;
  • discovers .claude/settings.json and .claude/settings.local.json;
  • does not follow symbolic links;
  • prints a summary and concise details for each active finding without creating report files;
  • supports --quiet when only the summary is needed.

Reading results​

Each finding has a rule ID, severity, confidence, location, risk explanation, recommended fix, and stable fingerprints.

When no report path is provided, the text output includes each active finding's severity, rule ID, location, risk, and recommended fix. Secret evidence remains redacted. Use --quiet to print only the scan summary, for example in a compact CI log.

SeverityMeaning
CRITICALImmediate security concern, such as exposed credentials, code execution, or direct exfiltration
HIGHSerious weakness that should be addressed before publication or deployment
MEDIUMSuspicious or context-dependent behavior requiring review
LOWLower-impact hygiene or transport concern
INFOMissing prompt-level control or informational guidance

Secret evidence is shown as [REDACTED] by default. Do not paste credentials into reports or issue comments. If a credential was real, rotate it and audit repository history.

Limit displayed findings:

ai-primitives-hub security scan . --minimum-severity HIGH
ai-primitives-hub security scan . --severity CRITICAL --severity HIGH

The severity filter controls the reported findings. The failure policy is independent:

ai-primitives-hub security scan . --fail-on HIGH

--fail-on HIGH fails when an unsuppressed HIGH or CRITICAL finding exists, even if the displayed report was narrowed with a severity filter.

Prompt-control checks​

Missing LLM controls are disabled by default because they can be noisy for general documentation. Enable them explicitly for prompts, agents, and skills:

ai-primitives-hub security scan . --include-llm-controls

To omit the informational CTL-001–CTL-013 checks while retaining active controls:

ai-primitives-hub security scan . --include-llm-controls --skip-info-controls

These checks assess instructions written in an artifact. They do not enforce runtime IAM, sandboxing, rate limits, authentication, or output filtering.

False positives and ignored files​

Use .markdown.ignore for a triaged finding. Put one fingerprint on each line:

# Legacy exact-occurrence token; use the narrowest directory scope
0123456789abcdef0123456789abcdef # explain the accepted false positive

A finding's fingerprint uses the basename, rule, line and normalized content. Identical occurrences in same-basename files can share a token within the ignore scope; it is not guaranteed to isolate one file across a tree. Its canonical fingerprint suppresses the same rule/content pattern more broadly. Use the narrowest directory scope and review the suppressed findings. The report provides copyable values.

Use .markdown-file.ignore to exclude complete files:

# Simple filename
examples.md

# Relative path or glob
references/*.md
docs/**

Both files support blank lines and # comments. They apply to their directory subtree and applicable ancestors. Ignore files are bounded and malformed entries are reported.

CI trust modes​

Repository-controlled ignore files can hide findings introduced by a pull request. CI should use:

ai-primitives-hub security scan . --ci

--ci uses fail-closed defaults, including --ignore-trust none. The explicit modes are:

  • repository — honor repository ignore files; suitable for local triage;
  • none — honor neither repository suppression nor whole-file ignore files;
  • baseline — use only caller-supplied, trusted baseline files.

For baseline mode, provide files from a protected source rather than from the pull request under test:

ai-primitives-hub security scan . \
  --ci --ignore-trust baseline \
  --baseline-suppressions /protected/baseline/.markdown.ignore \
  --baseline-file-ignore /protected/baseline/.markdown-file.ignore

Reports and automation​

Reports are opt-in:

ai-primitives-hub security scan . \
  --report-json artifacts/security.json \
  --report-markdown artifacts/security.md

The files are written atomically. Secret evidence remains redacted. JSON, YAML, and NDJSON are intended for automation; Markdown is intended for review.

The CLI exits with:

CodeMeaning
0Complete scan and failure policy passed
1Complete scan but the failure policy was not met
64Invalid command usage
65Incomplete scan, missing input, limit, or cancellation outcome
70Unexpected software failure
74Report or input filesystem failure

Use the bundled composite action to scan changed Markdown and Claude settings files, upload reports, and apply an explicit failure policy:

permissions:
  contents: read

steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    with:
      fetch-depth: 0
  - uses: AmadeusITGroup/ai-primitives-hub/github-actions/security-scan@<commit-sha>
    with:
      cli-version: '<scanner-enabled-version>'
      fail-on: HIGH

Pin the action to a full commit SHA and select an exact published CLI release that includes security scan; releases predating the scanner cannot run this action. Set pull-requests: write and comment-on-pr: 'true' only when the workflow should add a pull request comment. The action invokes the released CLI with --ci --ignore-trust none. If comment posting is denied (for example on a fork), the action emits a warning without changing the scan's exit status. Use the uploaded report.

VS Code​

The AI Primitives Hub extension provides:

  • Security Scan Current File;
  • Security Scan Workspace;
  • Show Last Security Report;
  • Clear Security Diagnostics.

Show Last Security Report opens a detailed report with risks, recommended fixes, and suppression fingerprints. The status bar shows the latest active finding count.

Screenshot placeholder: the security report beside a Markdown editor, with a redacted finding, Problems diagnostics, and the security status-bar count.

Automatic open and save scans are enabled by default only for trusted local file: workspaces. They are disabled for untrusted or virtual workspaces. Automatic scans are debounced, and a newer scan supersedes an older scan for the same file or workspace. Already-open Markdown documents are considered when the extension activates. Manual current-file scans also accept .claude/settings.json and .claude/settings.local.json; automatic document scans remain Markdown-only. Changing minimumSeverity immediately re-filters cached diagnostics and the report in either direction without rescanning. Newer file and workspace scans cannot be overwritten by older results covering the same file.

Configure the extension under promptregistry.security.*. See the Settings Reference. The extension uses the shared scanner and does not require Python.

Limitations​

Static scanning cannot determine runtime behavior or prove that an artifact is safe. It can miss context-specific attacks and can report examples or intentionally educational text. Use confidence, review the surrounding artifact, remediate real findings, and suppress only after triage.

The scanner does not modify source files automatically. It should be combined with repository review, least-privilege tool configuration, secret management, sandboxing, dynamic testing, and an appropriate security approval process.

See also​