ContextShield

ContextShield is a defensive command-line scanner for files and folders that may be shared outside a trusted environment. It identifies secrets, internal references, risky instruction text, and encoded content that should be reviewed before publication or third-party transfer.

Maintainer: CodeWithAmeer

Project Links

• Security Policy
• Contributing Guide
• Architecture Notes

Quick Validation

cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo run -- scan ./samples/clean
cargo run -- scan ./samples/suspicious --json report.json --html report.html

Features

• Recursive file and directory scanning
• Parallel scanning for large repositories
• Safe handling for unsupported and oversized files
• Secret, token, credential, private key, and high-entropy value detection
• Internal URL, private IP, localhost, and internal hostname detection
• Suspicious instruction override and hidden prompt request detection
• Large encoded blob detection
• Per-finding, per-file, and overall risk scoring
• Safe redaction by default
• Terminal, JSON, and HTML reports
• Project-level configuration through contextshield.toml

Why this project exists

Modern projects often contain internal notes, configuration fragments, logs, scripts, and samples that are useful during development but unsafe to share externally. ContextShield gives maintainers a fast local review step before content leaves a trusted workspace.

The tool is strictly defensive. It does not include exploitation, intrusion, persistence, evasion, payload delivery, credential abuse, attack orchestration, or bypass functionality.

Installation

Install from a local checkout:

cargo install --path .

Or build and run directly:

cargo build --release
./target/release/contextshield scan ./samples

Build and validation

cargo build
cargo test
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings

Usage

Scan a directory:

contextshield scan ./samples

Write JSON and HTML reports:

contextshield scan ./samples --json report.json --html report.html

Use a custom configuration file:

contextshield scan ./src --config contextshield.toml

Fail when findings meet or exceed a severity level:

contextshield scan ./release-notes --fail-on-severity medium

Suppress terminal output while still writing reports:

contextshield scan ./samples --json report.json --quiet

Sample terminal output

ContextShield scan summary
Target: ./samples
Files scanned: 7
Files skipped: 1
Findings: 5
Overall risk score: 88/100
Failure threshold: high
Highest severity: high

Findings by severity:
  - high: 2
  - medium: 2
  - low: 1

Findings by category:
  - API key: 1
  - Encoded blob: 1
  - Hidden prompt request: 1
  - Internal URL: 1
  - Localhost reference: 1
JSON report: report.json
HTML report: report.html

Configuration

ContextShield looks for contextshield.toml in the current working directory unless --config is provided.

allowed_internal_domains = ["docs.internal"]
ignored_paths = [".git", "target", "node_modules", "fixtures/private"]
max_file_size = 5242880
severity_threshold = "high"
include_extensions = []
exclude_extensions = ["png", "jpg", "jpeg", "gif", "zip"]

[detectors]
secrets = true
prompt_injection = true
internal_refs = true
encoding = true

Configuration fields

Field	Description
allowed_internal_domains	Internal domains that are expected and should not be reported. Subdomains are also allowed.
ignored_paths	Path components or path fragments to skip during recursive scans.
max_file_size	Maximum file size in bytes. Larger files are skipped safely.
severity_threshold	Default failure threshold: info, low, medium, high, or critical.
include_extensions	When set, only these extensions are scanned. Values may include or omit a leading dot.
exclude_extensions	Extensions that should always be skipped.
[detectors]	Enables or disables individual detectors.

JSON report example

{
  "tool": "ContextShield",
  "version": "0.1.0",
  "maintainer": "CodeWithAmeer",
  "root_path": "./samples",
  "files_scanned": 1,
  "files_skipped": 0,
  "total_findings": 1,
  "overall_risk_score": 68,
  "files": [
    {
      "path": "samples/suspicious/app.env",
      "size_bytes": 41,
      "sha256": "846fb576c30d0c4a76f42be53a03825c31d41193627975cfb3988fb998b3e640",
      "risk_score": 68,
      "findings": [
        {
          "category": "api_key",
          "severity": "high",
          "confidence": 0.9,
          "risk_score": 68,
          "explanation": "API key assignment contains a value that should not be shared.",
          "snippet": "API_KEY=[REDACTED]",
          "file_path": "samples/suspicious/app.env",
          "line_number": 1
        }
      ]
    }
  ],
  "skipped_files": []
}

Timestamps and durations are included in real reports. Secret values are redacted before reports are written.

Detection categories

Category	Purpose
hardcoded_secret	Private keys or secret-like assignments.
api_key	API key assignments and known key patterns.
access_token	Repository, workspace, bearer, session, and signed token patterns.
high_entropy_secret	Random-looking values in sensitive context.
env_file	Sensitive content in environment-style files.
credential	Passwords, database URLs, and credential assignments.
internal_url	Internal hostnames, routes, or private URL targets.
localhost_reference	Localhost or loopback references.
internal_ip_address	Private, link-local, loopback, or unspecified IP addresses.
prompt_injection	Suspicious instruction text intended to manipulate downstream processing.
instruction_override	Attempts to override or ignore existing instructions.
hidden_prompt_request	Requests for hidden, privileged, or system-level instructions.
encoded_blob	Large encoded-looking content that should be reviewed.

Exit codes

• 0: scan completed and no findings met or exceeded the configured failure threshold
• 1: scan completed and at least one finding met or exceeded the failure threshold
• 2: runtime error, invalid configuration, or invalid target

Limitations

ContextShield is a local static scanner. It cannot prove that a file is safe, and it may report benign content that resembles sensitive material. Treat findings as review prompts rather than final decisions. Binary formats, archives, and very large files are skipped unless converted or extracted before scanning.

Roadmap

• SARIF output
• Baseline files for existing accepted findings
• Additional file type metadata checks
• Optional allowlist entries for known benign values
• Optional report branding settings

Contributing

Contributions are welcome. Please keep the project defensive, practical, and easy to audit.

Before opening a pull request, run:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

Include tests for detector changes and avoid adding noisy patterns without clear security value.

License

MIT. See LICENSE.