convez.ai
MCP Server
HakuBlue

LokiRed

HakuBlue/LokiRed

Ver no GitHub
BomPluginScore · de 0 a 100

Local-first CLI and GitHub Action for AI-agent and MCP configuration risk.

Instalação

$npx convez-ai HakuBlue/LokiRed

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 3 meses
Versão
v0.2.2
Issues abertas
1
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

LokiRed

LokiRed Tests License

LokiRed is a CLI scanner for AI-agent and MCP configuration risk.

It helps you answer:

Which AI coding agents can access which tools, repos, secrets, tokens, and systems, and what risky configuration changes are being introduced?

LokiRed is built for teams using tools such as Codex, Claude Code, Cursor, Windsurf, GitHub Copilot coding agent, and MCP servers. It scans a repository or workspace, finds supported agent configuration files, and reports risky patterns with file paths, line numbers, evidence, severity, confidence, recommended action, and remediation guidance.

Project Status

LokiRed Community v0.1.0 is an early CLI-first MVP. The scanner is deterministic, local-first, and useful without a hosted service.

The current 0.1.x line focuses on repo and workspace scanning, CI enforcement, normalized inventory, policy, suppressions, baselines, and SARIF. Output schema details, supported ecosystems, and the rule set may still evolve while the project is pre-1.0, but the goal is stable, evidence-first findings that can run repeatably in CI.

What LokiRed Checks

LokiRed currently detects:

  • Hardcoded secrets in supported agent and MCP config files.
  • Hardcoded secrets in agent-facing instruction files.
  • Destructive shell or database commands in MCP startup commands.
  • Destructive commands in agent instruction text.
  • MCP servers using insecure remote http:// URLs.
  • MCP tools or servers configured for auto approval.
  • Claude Code command, HTTP, and prompt hooks that run during lifecycle events.
  • Claude Code settings that bypass permission prompts.
  • Claude Code settings that auto-enable all project MCP servers.
  • Overbroad Claude Code tool allow rules.
  • Codex configs with disabled approvals.
  • Codex configs with full filesystem access.
  • Codex filesystem and network permission-profile semantics in normalized inventory.
  • VS Code workspace and dev-container MCP servers.
  • Committed GitHub Copilot setup workflow commands as static inventory.
  • Invalid JSON or TOML in supported config files.

LokiRed also produces an inventory of discovered agent configuration files when using JSON output. JSON output includes report schema version 1.1, a versioned normalized inventory, permission classifications, stable finding fingerprints, policy and suppression metadata, coverage warnings, and optional baseline diff state.

Rules include first-class confidence and recommended action metadata. Confidence communicates evidence strength (high, medium, low, or unknown). Recommended action communicates the rule library's default recommendation (warn or block) without changing the CLI --fail-on severity threshold behavior.

Supported Files

LokiRed discovers and scans these files today:

EcosystemFiles
Generic MCPmcp-config.json
Claude MCP.mcp.json
Claude Code settings.claude/settings.json, .claude/settings.local.json
Codex.codex/config.toml
Cursor MCP.cursor/mcp.json
Cursor rules.cursorrules, .cursor/rules/*.md, .cursor/rules/*.mdc
VS Code workspace MCP.vscode/mcp.json
VS Code dev-container MCP.devcontainer/devcontainer.json with customizations.vscode.mcp.servers
Windsurf MCPmcp_config.json
GitHub Copilot instructions.github/copilot-instructions.md, .github/instructions/*.instructions.md
GitHub Copilot prompts.github/prompts/*.prompt.md
GitHub Copilot setup workflow.github/workflows/copilot-setup-steps.yml, .github/workflows/copilot-setup-steps.yaml
General agent instructionsAGENTS.md, CLAUDE.md, GEMINI.md

LokiRed skips common generated or dependency folders such as .git, node_modules, vendor, dist, build, .venv, venv, .pytest_cache, and __pycache__.

See docs/coverage.md for the full coverage matrix and the blind spots LokiRed reports honestly in JSON and Markdown review output.

Requirements

  • Python 3.11 or newer.
  • No third-party Python packages are required for scanner runtime.
  • SARIF schema-validation tests use the optional test extra.

On Windows, make sure python --version works before continuing.

Install For Local Development

From the repository root:

python -m pip install -e .

This installs the lokired command in editable mode, which means changes to the source files are picked up immediately.

You can also run LokiRed without installing:

python -m lokired scan .

Quick Start

Scan the current folder:

lokired scan .

Scan a specific folder:

lokired scan C:\path\to\your\repo

Scan this repository's realistic test workspace:

lokired scan test-environment

If LokiRed finds issues, the default text output looks like this:

LokiRed scan findings
=====================
Total issues: 9
Active issues: 9

1. [CRITICAL] UNSAFE_APPROVAL_MODE
   Title: Agent approvals are disabled
   Confidence: high
   Recommended action: block
   File: .codex\config.toml
   Config type: Codex configuration
   Line: 1

   Risk:
   Codex is configured with approval_policy='never', reducing human checkpoints for tool use.

   Evidence:
   Setting: approval_policy
   Value: never

   Remediation:
   Use an approval policy that prompts before risky tool use in shared or CI-controlled workspaces.

Command Reference

Primary scan command:

lokired scan [folder_path] [--format text|json|sarif] [--fail-on low|medium|high|critical|none] [--policy path] [--baseline path] [--write-baseline path] [--verbose]

Arguments:

  • folder_path: Folder to scan. Defaults to the current directory.
  • --format: Output format. Defaults to text.
  • --fail-on: Exit with code 1 when findings are at or above the chosen severity. Defaults to low.
  • --policy: Optional explicit policy file path. Without this flag, LokiRed discovers .lokired/policy.yml, then legacy .lokired.yml or .lokired.yaml in the scan root when present.
  • --baseline: Optional LokiRed baseline JSON file. Findings are classified as new, unchanged, or resolved.
  • --write-baseline: Write active findings from the scan to a versioned baseline JSON file.
  • --verbose: Show machine-oriented details such as finding fingerprints in text output.

Severity options:

  • low
  • medium
  • high
  • critical
  • none

Use --fail-on none when you want a report but do not want the command to fail.

Policy validation:

lokired policy validate
lokired policy validate --policy .lokired/policy.yml

Rule catalog inspection:

lokired rules list
lokired rules show INSECURE_REMOTE_MCP

Output Formats

Text

Best for humans reading results in a terminal:

lokired scan . --format text

Text output uses paths relative to the scan root when possible, expands internal config identifiers into readable labels, and formats evidence across multiple lines. Use --verbose when you want fingerprints in the terminal report:

lokired scan . --format text --verbose

JSON

Best for scripts, dashboards, and inventory:

lokired scan . --format json

The JSON report includes:

  • Tool name and version.
  • Report schema version 1.1.
  • Summary counts by severity.
  • Summary counts by config type.
  • Full finding details.
  • Inventory of discovered config files.
  • Versioned normalized inventory records, including clients, servers, capabilities, and evidence.
  • Permission classifications.
  • Coverage warnings for user-profile, SaaS-managed, and local-only surfaces outside the explicit scan root.
  • Stable finding fingerprints.
  • Finding confidence, recommended action, policy decision when applicable, and baseline state when applicable.
  • Suppressed findings and suppression review metadata when policy suppressions are used.
  • Baseline diff state and permission graph-delta summaries when --baseline is used.

Example shape:

{
  "report_schema_version": "1.1",
  "tool": {
    "name": "LokiRed",
    "version": "0.1.0"
  },
  "summary": {
    "total": 9,
    "by_severity": {
      "critical": 1,
      "high": 4,
      "medium": 4
    }
  },
  "inventory": {
    "total_config_files": 8,
    "normalized": {
      "schema_version": "1.0",
      "clients": [],
      "servers": [],
      "capabilities": [],
      "evidence": [],
      "resources": [],
      "identities": [],
      "permissions": [],
      "bindings": []
    }
  },
  "coverage_warnings": [],
  "classifications": [],
  "findings": []
}

SARIF

Best for GitHub code scanning and security tooling:

lokired scan . --format sarif

To save SARIF to a file:

lokired scan . --format sarif --fail-on none > lokired.sarif

SARIF includes stable rule ids, rule metadata, confidence, recommended action, relative file locations when a scan root is known, remediation guidance, redacted evidence, and lokiredFingerprint/v1 partial fingerprints for GitHub code scanning deduplication.

Default SARIF is optimized for active code-scanning alerts. Suppressed findings, resolved baseline findings, and raw permission graph deltas are not emitted as ordinary SARIF results. JSON is the complete local audit artifact for inventory, suppressions, resolved state, and detailed graph deltas.

Policies And Suppressions

LokiRed policy files are local, versioned, and optional. By default, LokiRed looks for .lokired/policy.yml in the scan root. Legacy .lokired.yml and .lokired.yaml remain supported when the canonical path is absent. If more than one implicit policy file exists, LokiRed exits with status 2 and asks you to remove the ambiguity or pass --policy. An explicit --policy path always wins.

Example:

schema_version: 1

access:
  allow:
    - resource: workspace
  warn:
    - resource: "network:*"
  block:
    - category: secret
      access: read_secret_literal
      severity: critical
      reason: Literal secrets are not allowed in agent config.
  require-review:
    - resource: "filesystem:/"

rules:
  INSECURE_REMOTE_MCP:
    severity: high

suppressions:
  - rule_id: HARDCODED_SECRET
    path: mcp-config.json
    config_path: mcpServers.github.env.GITHUB_TOKEN
    reason: Synthetic fixture credential.
    owner: appsec
    expires: 2099-01-01
    ticket: SEC-123

Supported access actions are allow, warn, block, and require-review. Legacy access.deny is accepted as an alias for access.block. If more than one action matches the same classified access, precedence is block, then require-review, then warn, then allow.

block and require-review create policy findings and enforce a non-zero CLI exit even when --fail-on none is used. warn creates a visible policy finding but does not fail by itself. allow permits the matching classified access but does not suppress independent scanner findings.

Unknown access actions, malformed action lists, pattern-level action fields, malformed YAML, and unsupported schema versions exit with status 2.

Suppression entries require rule_id, non-empty path, non-empty reason, non-empty owner, and an expires date in YYYY-MM-DD format. Optional fingerprint, config_path, and resource selectors can narrow a suppression further, but they do not replace file scope. Expired, unused, malformed, resource-only, or overly broad suppressions are reported instead of silently hiding findings.

Baseline Diff Scanning

Create a baseline:

lokired scan . --format json --write-baseline .lokired-baseline.json --fail-on none

Use a baseline:

lokired scan . --baseline .lokired-baseline.json --fail-on high

Baseline files use schema version 2.0. They store finding fingerprints and an inventory_graph snapshot with normalized clients, servers, capabilities, and evidence. In baseline mode, active findings are marked as new or unchanged, findings that disappeared are listed as resolved, and graph deltas are reported as added, removed, changed, expanded, or narrowed. CI thresholds apply only to new active findings when --baseline is supplied. Without a baseline, threshold behavior is unchanged.

Legacy schema 1.0 finding-only baselines still load for finding diffing, but graph diff is marked unavailable until the baseline is regenerated.

Using LokiRed In CI

The --fail-on option controls whether LokiRed exits successfully or fails the build.

Fail on high or critical findings:

lokired scan . --fail-on high

Fail only on critical findings:

lokired scan . --fail-on critical

Never fail, only report:

lokired scan . --fail-on none

Exit codes:

  • 0: No findings at or above the configured threshold.
  • 1: One or more findings at or above the configured threshold.
  • 2: Scan setup failed, such as malformed policy, malformed baseline, or an invalid scan path.

Example GitHub Actions Workflow

This repository includes action.yml, a thin composite action that invokes the CLI. In another repository, pin LokiRed to a release tag. Inside this repository, uses: ./ runs the local checkout.

Using the bundled action from a checkout:

- name: Scan agent and MCP config
  uses: ./
  with:
    scan-path: "."
    output-format: "text"
    fail-on: "high"

Create .github/workflows/lokired.yml:

name: LokiRed

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  scan:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Install LokiRed
        run: python -m pip install -e .

      - name: Scan agent and MCP config
        run: lokired scan . --format text --fail-on high

To upload SARIF into GitHub code scanning, enable code scanning for the repository first. The checked-in SARIF workflow skips the upload step by default so repositories without code scanning enabled still pass CI. After enabling code scanning, set the repository variable LOKIRED_UPLOAD_CODE_SCANNING to true.

Example SARIF upload workflow:

name: LokiRed SARIF

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      security-events: write
      contents: read

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Install LokiRed
        run: python -m pip install -e .

      - name: Generate SARIF
        run: lokired scan . --format sarif --fail-on none > lokired.sarif

      - name: Upload SARIF
        if: vars.LOKIRED_UPLOAD_CODE_SCANNING == 'true' && github.event_name == 'push'
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: lokired.sarif

      - name: Enforce threshold
        run: lokired scan . --format text --fail-on high

How To Read A Finding

Each finding includes:

  • Severity: How risky LokiRed considers the issue.
  • Rule ID: Stable identifier for the rule that fired.
  • Title: Short explanation of the problem.
  • Confidence: Evidence strength for the finding.
  • Recommended action: Catalog recommendation, separate from CLI threshold behavior.
  • File: The file containing the issue.
  • Config type: The detected config ecosystem, shown as a readable label in text output.
  • Line: Where LokiRed found the evidence.
  • Risk: Why the finding matters.
  • Evidence: The exact config path, server name, operation, or setting involved.
  • Fingerprint: Stable finding identity used by suppressions, baselines, and SARIF. Text output shows this only with --verbose; JSON and SARIF always include machine-readable fingerprints.
  • Remediation: Practical guidance for fixing it.

Example:

[HIGH] HARDCODED_SECRET
File: mcp-config.json
Line: 10

Evidence:
Setting: mcpServers.github.env.GITHUB_TOKEN
Key: GITHUB_TOKEN
Value: <redacted>

Remediation:
Load this value from a secret manager or environment variable reference instead of committing the secret directly.

Fix:

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}

Local Test Workspace

This repository includes test-environment, a realistic sample workspace with safe and risky agent configuration files.

Run:

lokired scan test-environment --format text --fail-on none

Expected current result:

  • 8 discovered config files.
  • 9 findings.
  • 1 critical finding.
  • 4 high findings.
  • 4 medium findings.

This fixture is useful when changing scanner behavior because it checks real-world concerns:

  • Multiple agent ecosystems in one workspace.
  • Safe instruction files beside risky configuration.
  • Secrets and remote MCP settings.
  • CI threshold behavior.
  • Ignored dependency and vendor folders.

When scanning this repository root, .lokired.yml suppresses these intentionally risky fixture findings so the public CI checks LokiRed without failing on its own examples. Scanning test-environment directly still reports the expected findings above.

Running Tests

Run the test suite:

python -m pip install -e ".[test]"
python -m unittest discover -s tests -v

The tests cover:

  • MCP structural rules.
  • Safe config negative cases.
  • Text, JSON, and SARIF reporters.
  • Realistic mixed workspace scanning.
  • Supported ecosystem discovery.
  • Normalized inventory serialization.
  • Permission classification.
  • Policy actions, legacy deny handling, severity overrides, and malformed policy rejection.
  • Accountable active, expired, invalid, and unused suppressions.
  • Baseline generation, finding diff results, graph persistence, and graph deltas.
  • Local SARIF 2.1.0 schema validation with the vendored schema in tests/vendor/sarif.
  • Direct negative cases for every catalog rule.
  • Static no-execution regression coverage for MCP startup commands.
  • CI threshold behavior.
  • CLI JSON output and exit codes.
  • GitHub Action metadata.
  • Deterministic output ordering.

Contributing And Security

See CONTRIBUTING.md for local setup, fixture expectations, and pull request guidance.

See SECURITY.md for responsible vulnerability reporting. Please do not open public issues containing real secrets, private repository contents, or customer configuration.

Compatibility Wrapper

For early prototype compatibility, run_scanner.py still exists.

These are equivalent:

python -m lokired scan test-environment
python run_scanner.py test-environment

New usage should prefer:

lokired scan test-environment

or:

python -m lokired scan test-environment

Current Limitations

LokiRed is intentionally deterministic and local-first in this MVP.

Current limitations:

  • It does not call an LLM to judge severity.
  • It does not require cloud connectivity.
  • It does not upload config contents.
  • It does not yet scan every AI-agent ecosystem.
  • It focuses on high-signal config and instruction risks, not full secret scanning across every file.
  • Its built-in YAML parser supports the policy subset documented in this repository rather than the full YAML specification.
  • Repository scans do not automatically cover local user-profile settings outside the scanned path.
  • Repository scans do not automatically cover SaaS-managed repository settings.
  • It does not yet ship a hosted GitHub App or team dashboard.
  • The initial CLI does not observe runtime MCP traffic or tool calls.

Rule Documentation

Detailed rule documentation lives in docs/rules, with a broader workflow guide in docs/guide.md. See also the threat model and privacy model. Each rule page documents the rule id, title, trigger, severity, confidence, recommended action, evidence, remediation, false-positive considerations, and suppression guidance.

Development Notes

Project layout:

lokired.py                         CLI entrypoint and scan orchestration
security_file_scanner.py           Discovery and deterministic rules
inventory.py                       Versioned normalized inventory schema
classification.py                  Permission classification over inventory
policy.py                          Policy, suppressions, and policy deny findings
baseline.py                        Baseline creation, validation, and diffing
fingerprints.py                    Stable finding fingerprints
rule_catalog.py                    Stable rule metadata
reporter.py                        Text, JSON, and SARIF output
action.yml                         Thin GitHub Action wrapper around the CLI
docs/                              Workflow and rule documentation
run_scanner.py                     Compatibility wrapper
tests/                             Unit and pipeline tests
mock_configs/                      Small MCP fixtures
test-environment/                  Realistic mixed workspace fixture

LokiRed's MVP design goal is to stay evidence-first:

  • Every finding should say what was found.
  • Every finding should say where it was found.
  • Every finding should say why it matters.
  • Every finding should include practical remediation guidance.

Roadmap Ideas

Near-term direction after v0.1.0:

  • Keep improving pull-request review artifacts around baseline inventory and graph deltas.
  • Expand high-signal coverage for repo-visible agent and MCP configuration surfaces.
  • Make GitHub Action onboarding and branch-protection rollout easier for warn-only and enforced modes.
  • Keep policy, suppressions, and rule documentation practical for AppSec, platform, DevEx, and developer reviewers.

Longer-term direction:

  • GitHub App and team inventory views for organization-wide coverage, policy, exceptions, and evidence.
  • Optional endpoint visibility for local user-profile agent configuration that is outside repository scans.
  • Runtime MCP enforcement or gateway work only after the static governance workflow proves demand.

License

LokiRed Community is licensed under the Apache License 2.0. See LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados