Context Armor

Know what an AI agent can see before it sees it.

Context Armor is a zero-dependency, local-first preflight scanner for secrets, personal data, and risky documents in AI workspaces. It scans source code and the business files that ordinary repository scanners miss: DOCX, XLSX, PPTX, PDF, and optionally images.

npx context-armor scan .

No account. No upload. No telemetry. Raw findings never appear in reports.

Status: early release. Context Armor is useful today, but it is not a substitute for credential rotation, access control, or a full DLP program.

Why this exists

AI coding agents routinely receive access to an entire working directory. Real workspaces are rarely clean Git repositories: they contain contracts, tax exports, identity scans, screenshots, old backups, API keys, and customer lists.

Most secret scanners answer, “Is this safe to commit?” Context Armor answers a different question:

“Is this directory safe to expose to an AI agent?”

It was built after a real small-business workspace audit found credentials and personal documents mixed into the same directory as web projects.

What makes it different

| Capability | Context Armor | | --- | --- | | Runs fully locally | Yes | | Runtime dependencies | Zero | | Source and plain-text files | Yes | | DOCX / XLSX / PPTX | Built-in ZIP/XML extraction | | PDF | Local pdftotext, when installed | | Images | Optional local Tesseract OCR | | Korean PII | Checksum-aware resident number and phone rules | | Safe reports | Redacted evidence plus one-way fingerprints | | AI-tool protection | Claude settings, .cursorignore, .geminiignore | | CI integration | GitHub Action, JSON, and SARIF | | Baseline support | Yes |

Context Armor complements runtime agent firewalls and traditional secret scanners. It focuses on mixed, pre-existing workspace context before a session begins.

Quick start

Requires Node.js 20 or newer.

# One-off scan
npx context-armor scan .

# Install globally
npm install --global context-armor
context-armor scan ~/work/project

# Fail CI on high or critical findings
context-armor scan . --fail-on high

# Create local ignore and configuration files
context-armor init .

Example output:

Context Armor scanned 247 files in 183ms

CRITICAL config/local.env:3:9 SECRET_ANTHROPIC_KEY
         An Anthropic API key was found.
HIGH     documents/id-scan.pdf FILE_IDENTITY_DOCUMENT_KR
         The filename indicates a Korean identity document.
LOW      README.md:42:11 PII_EMAIL
         An email address was found.

1 critical · 1 high · 0 medium · 1 low

The matched key, identity number, email, or card number is never printed or serialized.

Protect a workspace

protect scans the directory and writes local deny lists for supported agents:

context-armor protect .

It creates or updates:

• .cursorignore
• .geminiignore
• .claude/settings.local.json
• .context-armor/protected-paths.txt

Only paths with findings at or above the selected threshold are protected. Existing Cursor and Gemini ignore content is preserved in a clearly marked block. Existing Claude settings are merged, not replaced.

# Protect medium, high, and critical paths
context-armor protect . --fail-on medium

Review generated policies before starting an agent. Ignore files are a defense-in-depth convenience, not a security sandbox.

Rich documents

Context Armor treats an AI workspace as more than source code:

| Format | Behavior | | --- | --- | | DOCX | Extracts document, header, footer, and comment XML | | XLSX | Extracts shared strings and worksheet XML | | PPTX | Extracts slide and speaker-note XML | | PDF | Uses local pdftotext; reports reduced coverage if unavailable | | PNG/JPEG/TIFF/WebP | Uses local Tesseract only with --ocr | | Legacy DOC/XLS/PPT | Filename rules only; richer extraction is planned |

Install optional local extractors:

# macOS
brew install poppler tesseract tesseract-lang

# Ubuntu / Debian
sudo apt-get install poppler-utils tesseract-ocr

Then verify coverage:

context-armor doctor
context-armor scan . --ocr --ocr-languages eng+kor

Rules

The initial ruleset covers:

• Private keys, AWS access keys, GitHub tokens
• Anthropic, OpenAI, Google, Slack, and Stripe credentials
• Database URLs with embedded credentials
• JSON Web Tokens and hard-coded passwords
• Luhn-valid payment card numbers
• Korean resident registration numbers with legacy checksum validation
• Korean mobile numbers, US SSNs, and email addresses
• Sensitive filenames for environment files, keys, credentials, dumps, and Korean identity, financial, and legal documents

Rules favor precision over counting every possible secret. Please open an issue for false positives or missing formats—using synthetic data only.

Configuration

Run context-armor init . or create context-armor.config.json:

{
  "failOn": "high",
  "maxFileSize": "8mb",
  "maxFiles": 100000,
  "documents": true,
  "ocr": false,
  "respectGitignore": true,
  "ignore": ["fixtures/public/**"],
  "disabledRules": ["PII_EMAIL"],
  "severity": {
    "PII_KR_PHONE": "high"
  }
}

Context Armor also reads .contextarmorignore. Its syntax follows the common Git ignore subset: comments, glob patterns, directories, and ! negation.

Baselines

Adopt Context Armor without hiding new problems:

context-armor scan . --write-baseline .context-armor-baseline.json --fail-on none
context-armor scan . --baseline .context-armor-baseline.json --fail-on high

Baselines contain only one-way finding fingerprints.

GitHub Action

name: Context Armor
on: [push, pull_request]

permissions:
  contents: read
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: feelyday/context-armor@v0
        with:
          path: .
          fail_on: high
          output: context-armor-results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: context-armor-results.sarif

The action executes the checked-out release directly. It does not install package dependencies.

Library API

import { scan } from "context-armor";

const report = await scan(".", {
  failOn: "high",
  documents: true,
  ocr: false,
  disabledRules: ["PII_EMAIL"],
});

console.log(report.summary);

Privacy and threat model

• File content is processed in memory on the local machine.
• Context Armor makes no network requests.
• Reports contain paths, rule identifiers, locations, and redacted evidence lengths.
• Fingerprints are SHA-256-derived and intentionally do not preserve raw values.
• Symbolic links are not followed.
• ZIP extraction has entry and decompression bounds.
• External document tools are invoked with argument arrays, never through a shell.

Read SECURITY.md for limitations and reporting guidance.

Roadmap

• More country-specific, checksum-aware PII packs
• Better legacy Office and image metadata coverage
• Safe shadow-workspace mode for analysis-only sessions
• First-class hooks for more AI coding agents
• Policy packs for GDPR, HIPAA, and Korean PIPA workflows
• Community-maintained custom rules

한국어

Context Armor는 Claude, Codex, Cursor, Gemini 같은 AI 에이전트가 업무 폴더를 읽기 전에 API 키·개인정보·민감 문서를 로컬에서 점검하는 오픈소스 도구입니다. 소스코드뿐 아니라 DOCX, XLSX, PPTX, PDF와 선택적 이미지 OCR을 지원하며, 검사 내용은 외부로 전송하지 않습니다.

npx context-armor scan .
npx context-armor protect .

한국 주민등록번호는 단순 숫자 패턴이 아니라 날짜 형태와 구형 체크섬을 함께 검증합니다. 오탐이나 추가로 필요한 국내 문서 형식은 실제 개인정보가 아닌 합성 예제로 제보해 주세요.

Contributing

Bug reports, detection improvements, documentation, and regional PII expertise are welcome. See CONTRIBUTING.md.

Apache-2.0 © Context Armor contributors.