llm-keyguard 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- llm_keyguard/__init__.py +39 -0
- llm_keyguard/cli.py +136 -0
- llm_keyguard/py.typed +1 -0
- llm_keyguard/remediator.py +95 -0
- llm_keyguard/sarif.py +86 -0
- llm_keyguard/scanner.py +341 -0
- llm_keyguard/signatures.py +230 -0
- llm_keyguard-0.2.0.dist-info/METADATA +143 -0
- llm_keyguard-0.2.0.dist-info/RECORD +13 -0
- llm_keyguard-0.2.0.dist-info/WHEEL +5 -0
- llm_keyguard-0.2.0.dist-info/entry_points.txt +2 -0
- llm_keyguard-0.2.0.dist-info/licenses/LICENSE +21 -0
- llm_keyguard-0.2.0.dist-info/top_level.txt +1 -0
llm_keyguard/__init__.py
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""Public Python API for llm-keyguard."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from .remediator import generate_env_example, harden_gitignore, install_pre_commit_hook
|
|
6
|
+
from .sarif import build_sarif_report
|
|
7
|
+
from .scanner import (
|
|
8
|
+
Finding,
|
|
9
|
+
audit_mcp_configs,
|
|
10
|
+
audit_mcp_file,
|
|
11
|
+
scan_file,
|
|
12
|
+
scan_git_history,
|
|
13
|
+
scan_git_staged,
|
|
14
|
+
scan_path,
|
|
15
|
+
scan_text,
|
|
16
|
+
)
|
|
17
|
+
from .signatures import RULES, SecretRule, mask_secret, shannon_entropy
|
|
18
|
+
|
|
19
|
+
__version__ = "0.2.0"
|
|
20
|
+
|
|
21
|
+
__all__ = [
|
|
22
|
+
"__version__",
|
|
23
|
+
"Finding",
|
|
24
|
+
"RULES",
|
|
25
|
+
"SecretRule",
|
|
26
|
+
"audit_mcp_configs",
|
|
27
|
+
"audit_mcp_file",
|
|
28
|
+
"build_sarif_report",
|
|
29
|
+
"generate_env_example",
|
|
30
|
+
"harden_gitignore",
|
|
31
|
+
"install_pre_commit_hook",
|
|
32
|
+
"mask_secret",
|
|
33
|
+
"scan_file",
|
|
34
|
+
"scan_git_history",
|
|
35
|
+
"scan_git_staged",
|
|
36
|
+
"scan_path",
|
|
37
|
+
"scan_text",
|
|
38
|
+
"shannon_entropy",
|
|
39
|
+
]
|
llm_keyguard/cli.py
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
"""Command-line interface for llm-keyguard."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import sys
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import List, Optional, Sequence
|
|
10
|
+
|
|
11
|
+
from . import __version__
|
|
12
|
+
from .remediator import generate_env_example, harden_gitignore, install_pre_commit_hook
|
|
13
|
+
from .sarif import build_sarif_report
|
|
14
|
+
from .scanner import (
|
|
15
|
+
Finding,
|
|
16
|
+
audit_mcp_configs,
|
|
17
|
+
scan_git_history,
|
|
18
|
+
scan_git_staged,
|
|
19
|
+
scan_path,
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _emit_findings(findings: Sequence[Finding], fmt: str) -> None:
|
|
24
|
+
if fmt == "json":
|
|
25
|
+
payload = {
|
|
26
|
+
"version": __version__,
|
|
27
|
+
"count": len(findings),
|
|
28
|
+
"findings": [f.to_dict() for f in findings],
|
|
29
|
+
}
|
|
30
|
+
print(json.dumps(payload, indent=2))
|
|
31
|
+
return
|
|
32
|
+
if fmt == "sarif":
|
|
33
|
+
print(json.dumps(build_sarif_report(findings, version=__version__), indent=2))
|
|
34
|
+
return
|
|
35
|
+
|
|
36
|
+
if not findings:
|
|
37
|
+
print("llm-keyguard: OK (0 exposed credentials found)")
|
|
38
|
+
return
|
|
39
|
+
|
|
40
|
+
print(f"llm-keyguard: BLOCKED ({len(findings)} credential issue(s) detected)", file=sys.stderr)
|
|
41
|
+
for item in findings:
|
|
42
|
+
ctx = f" [{item.context_path}]" if item.context_path else ""
|
|
43
|
+
print(
|
|
44
|
+
f" [{item.rule_id}] {item.file}:{item.line}:{item.column}{ctx} -> "
|
|
45
|
+
f"{item.provider}: {item.masked}",
|
|
46
|
+
file=sys.stderr,
|
|
47
|
+
)
|
|
48
|
+
print(f" Fix: {item.remediation}", file=sys.stderr)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
52
|
+
parser = argparse.ArgumentParser(
|
|
53
|
+
prog="llm-keyguard",
|
|
54
|
+
description="Zero-dependency secret scanner, MCP config auditor, and Git pre-commit guard for LLM & AI API keys.",
|
|
55
|
+
)
|
|
56
|
+
parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
|
|
57
|
+
sub = parser.add_subparsers(dest="command", required=True)
|
|
58
|
+
|
|
59
|
+
p_scan = sub.add_parser("scan", help="Scan a directory or file for hardcoded API keys and MCP leaks")
|
|
60
|
+
p_scan.add_argument("target", nargs="?", default=".", help="Directory or file to scan (default: .)")
|
|
61
|
+
p_scan.add_argument("--include-dotenv", action="store_true", help="Also scan local .env files")
|
|
62
|
+
p_scan.add_argument("--format", choices=("text", "json", "sarif"), default="text", help="Output format")
|
|
63
|
+
|
|
64
|
+
p_staged = sub.add_parser("staged", help="Scan staged Git changes (for pre-commit hooks)")
|
|
65
|
+
p_staged.add_argument("--repo", default=".", help="Git repository root (default: .)")
|
|
66
|
+
p_staged.add_argument("--format", choices=("text", "json", "sarif"), default="text", help="Output format")
|
|
67
|
+
|
|
68
|
+
p_hist = sub.add_parser("history", help="Scan recent Git commit patches for leaked credentials")
|
|
69
|
+
p_hist.add_argument("--repo", default=".", help="Git repository root (default: .)")
|
|
70
|
+
p_hist.add_argument("-n", "--max-commits", type=int, default=50, help="Commits to inspect (default: 50)")
|
|
71
|
+
p_hist.add_argument("--format", choices=("text", "json", "sarif"), default="text", help="Output format")
|
|
72
|
+
|
|
73
|
+
p_mcp = sub.add_parser("audit-mcp", help="Audit MCP configuration files for hardcoded credentials")
|
|
74
|
+
p_mcp.add_argument("target", nargs="?", default=".", help="Directory or MCP file to inspect")
|
|
75
|
+
p_mcp.add_argument("--format", choices=("text", "json", "sarif"), default="text", help="Output format")
|
|
76
|
+
|
|
77
|
+
p_init = sub.add_parser("init", help="Harden .gitignore and install Git pre-commit hook")
|
|
78
|
+
p_init.add_argument("--repo", default=".", help="Target repository directory (default: .)")
|
|
79
|
+
p_init.add_argument("--no-hook", action="store_true", help="Only update .gitignore without installing hook")
|
|
80
|
+
|
|
81
|
+
p_env = sub.add_parser("env-example", help="Generate a safe .env.example from a local .env file")
|
|
82
|
+
p_env.add_argument("--source", default=".env", help="Source .env file (default: .env)")
|
|
83
|
+
p_env.add_argument("--output", default=".env.example", help="Destination template file (default: .env.example)")
|
|
84
|
+
|
|
85
|
+
return parser
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def main(argv: Optional[Sequence[str]] = None) -> int:
|
|
89
|
+
parser = build_parser()
|
|
90
|
+
args = parser.parse_args(argv)
|
|
91
|
+
|
|
92
|
+
if args.command == "scan":
|
|
93
|
+
findings = scan_path(Path(args.target), include_dotenv=args.include_dotenv)
|
|
94
|
+
_emit_findings(findings, args.format)
|
|
95
|
+
return 1 if findings else 0
|
|
96
|
+
|
|
97
|
+
if args.command == "staged":
|
|
98
|
+
findings = scan_git_staged(Path(args.repo))
|
|
99
|
+
_emit_findings(findings, args.format)
|
|
100
|
+
return 1 if findings else 0
|
|
101
|
+
|
|
102
|
+
if args.command == "history":
|
|
103
|
+
findings = scan_git_history(Path(args.repo), max_commits=args.max_commits)
|
|
104
|
+
_emit_findings(findings, args.format)
|
|
105
|
+
return 1 if findings else 0
|
|
106
|
+
|
|
107
|
+
if args.command == "audit-mcp":
|
|
108
|
+
findings = audit_mcp_configs(Path(args.target))
|
|
109
|
+
_emit_findings(findings, args.format)
|
|
110
|
+
return 1 if findings else 0
|
|
111
|
+
|
|
112
|
+
if args.command == "init":
|
|
113
|
+
repo = Path(args.repo).resolve()
|
|
114
|
+
added = harden_gitignore(repo)
|
|
115
|
+
if added:
|
|
116
|
+
print(f"llm-keyguard: added {len(added)} secret-protection rule(s) to {repo / '.gitignore'}")
|
|
117
|
+
else:
|
|
118
|
+
print(f"llm-keyguard: {repo / '.gitignore'} already hardened")
|
|
119
|
+
if not args.no_hook:
|
|
120
|
+
try:
|
|
121
|
+
hook_path = install_pre_commit_hook(repo)
|
|
122
|
+
print(f"llm-keyguard: installed Git pre-commit hook at {hook_path}")
|
|
123
|
+
except FileNotFoundError as exc:
|
|
124
|
+
print(f"llm-keyguard: skipped hook installation ({exc})", file=sys.stderr)
|
|
125
|
+
return 0
|
|
126
|
+
|
|
127
|
+
if args.command == "env-example":
|
|
128
|
+
mapping = generate_env_example(Path(args.source), Path(args.output))
|
|
129
|
+
print(f"llm-keyguard: generated {args.output} with {len(mapping)} sanitized variable(s)")
|
|
130
|
+
return 0
|
|
131
|
+
|
|
132
|
+
return 0
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
if __name__ == "__main__":
|
|
136
|
+
sys.exit(main())
|
llm_keyguard/py.typed
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# PEP 561 marker
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
"""Repository remediation utilities (.gitignore hardening, .env.example, and Git hooks)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import stat
|
|
7
|
+
import sys
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Dict, List
|
|
10
|
+
|
|
11
|
+
GITIGNORE_ENTRIES: List[str] = [
|
|
12
|
+
".env",
|
|
13
|
+
".env.*",
|
|
14
|
+
"!.env.example",
|
|
15
|
+
"!.env.sample",
|
|
16
|
+
"!.env.template",
|
|
17
|
+
"*.pem",
|
|
18
|
+
"*.key",
|
|
19
|
+
"*credentials*.json",
|
|
20
|
+
"*client_secret*.json",
|
|
21
|
+
]
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def harden_gitignore(repo_dir: Path) -> List[str]:
|
|
25
|
+
"""Ensure .gitignore protects .env and secret key files while allowing .env.example."""
|
|
26
|
+
gitignore_path = repo_dir / ".gitignore"
|
|
27
|
+
existing = gitignore_path.read_text(encoding="utf-8", errors="ignore") if gitignore_path.exists() else ""
|
|
28
|
+
present = {ln.strip() for ln in existing.splitlines() if ln.strip()}
|
|
29
|
+
missing = [rule for rule in GITIGNORE_ENTRIES if rule not in present]
|
|
30
|
+
if not missing:
|
|
31
|
+
return []
|
|
32
|
+
|
|
33
|
+
header = "# llm-keyguard secret protection"
|
|
34
|
+
block = "\n".join([header] + missing) + "\n"
|
|
35
|
+
updated = f"{existing.rstrip()}\n\n{block}" if existing.strip() else block
|
|
36
|
+
gitignore_path.write_text(updated, encoding="utf-8")
|
|
37
|
+
return missing
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def install_pre_commit_hook(repo_dir: Path) -> Path:
|
|
41
|
+
"""Install a lightweight Git pre-commit hook invoking `llm-keyguard staged`."""
|
|
42
|
+
hooks_dir = repo_dir / ".git" / "hooks"
|
|
43
|
+
if not hooks_dir.is_dir():
|
|
44
|
+
raise FileNotFoundError(f"No .git/hooks directory found under {repo_dir}")
|
|
45
|
+
|
|
46
|
+
hook_path = hooks_dir / "pre-commit"
|
|
47
|
+
py_exe = Path(sys.executable).as_posix()
|
|
48
|
+
script = (
|
|
49
|
+
"#!/bin/sh\n"
|
|
50
|
+
"# Installed by llm-keyguard\n"
|
|
51
|
+
f'"{py_exe}" -m llm_keyguard.cli staged\n'
|
|
52
|
+
"exit $?\n"
|
|
53
|
+
)
|
|
54
|
+
hook_path.write_text(script, encoding="utf-8", newline="\n")
|
|
55
|
+
try:
|
|
56
|
+
mode = hook_path.stat().st_mode
|
|
57
|
+
hook_path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
|
|
58
|
+
except OSError:
|
|
59
|
+
pass
|
|
60
|
+
return hook_path
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def generate_env_example(dotenv_path: Path, output_path: Path) -> Dict[str, str]:
|
|
64
|
+
"""Create a sanitized .env.example from a local .env file without exposing secret values."""
|
|
65
|
+
if not dotenv_path.is_file():
|
|
66
|
+
raise FileNotFoundError(f"Source .env file not found: {dotenv_path}")
|
|
67
|
+
|
|
68
|
+
out_lines: List[str] = []
|
|
69
|
+
sanitized_map: Dict[str, str] = {}
|
|
70
|
+
|
|
71
|
+
for raw_line in dotenv_path.read_text(encoding="utf-8", errors="ignore").splitlines():
|
|
72
|
+
stripped = raw_line.strip()
|
|
73
|
+
if not stripped or stripped.startswith("#") or "=" not in stripped:
|
|
74
|
+
out_lines.append(raw_line)
|
|
75
|
+
continue
|
|
76
|
+
key, val = stripped.split("=", 1)
|
|
77
|
+
key_clean = key.strip()
|
|
78
|
+
val_clean = val.strip().strip('"').strip("'")
|
|
79
|
+
placeholder = _placeholder_for_key(key_clean, val_clean)
|
|
80
|
+
sanitized_map[key_clean] = placeholder
|
|
81
|
+
out_lines.append(f"{key_clean}={placeholder}")
|
|
82
|
+
|
|
83
|
+
output_path.write_text("\n".join(out_lines) + "\n", encoding="utf-8")
|
|
84
|
+
return sanitized_map
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def _placeholder_for_key(key: str, val: str) -> str:
|
|
88
|
+
upper = key.upper()
|
|
89
|
+
if any(tok in upper for tok in ("KEY", "TOKEN", "SECRET", "PASSWORD", "PASSWD", "PAT", "CREDENTIAL")):
|
|
90
|
+
return f"your_{key.lower()}_here"
|
|
91
|
+
if val.startswith(("http://", "https://")):
|
|
92
|
+
return val
|
|
93
|
+
if val.lower() in {"true", "false", "0", "1", "development", "production"} or val.isdigit():
|
|
94
|
+
return val
|
|
95
|
+
return f"your_{key.lower()}_here"
|
llm_keyguard/sarif.py
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
"""OASIS SARIF v2.1.0 report builder for GitHub Code Scanning integration."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any, Dict, Sequence
|
|
6
|
+
|
|
7
|
+
from .scanner import Finding
|
|
8
|
+
from .signatures import RULES
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def build_sarif_report(findings: Sequence[Finding], version: str = "0.2.0") -> Dict[str, Any]:
|
|
12
|
+
"""Serialize findings into an OASIS SARIF v2.1.0 JSON-compatible dictionary."""
|
|
13
|
+
rule_catalog = [
|
|
14
|
+
{
|
|
15
|
+
"id": r.rule_id,
|
|
16
|
+
"name": r.provider,
|
|
17
|
+
"shortDescription": {"text": r.provider},
|
|
18
|
+
"help": {"text": r.remediation},
|
|
19
|
+
"defaultConfiguration": {"level": r.severity},
|
|
20
|
+
}
|
|
21
|
+
for r in RULES
|
|
22
|
+
] + [
|
|
23
|
+
{
|
|
24
|
+
"id": "LLMKG000",
|
|
25
|
+
"name": "Staged .env File",
|
|
26
|
+
"shortDescription": {"text": "Live .env file staged for Git commit"},
|
|
27
|
+
"help": {"text": "Unstage .env and add .env to .gitignore."},
|
|
28
|
+
"defaultConfiguration": {"level": "error"},
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
"id": "LLMKG101",
|
|
32
|
+
"name": "MCP Config Hardcoded Provider Key",
|
|
33
|
+
"shortDescription": {"text": "Hardcoded LLM/API credential inside MCP configuration"},
|
|
34
|
+
"help": {"text": "Inject MCP credentials via environment variables rather than literal strings."},
|
|
35
|
+
"defaultConfiguration": {"level": "error"},
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
"id": "LLMKG102",
|
|
39
|
+
"name": "MCP Config High-Entropy Credential",
|
|
40
|
+
"shortDescription": {"text": "High-entropy secret literal inside MCP configuration"},
|
|
41
|
+
"help": {"text": "Replace literal credential with an environment variable reference."},
|
|
42
|
+
"defaultConfiguration": {"level": "error"},
|
|
43
|
+
},
|
|
44
|
+
]
|
|
45
|
+
|
|
46
|
+
sarif_results = []
|
|
47
|
+
for f in findings:
|
|
48
|
+
msg = f"{f.provider} detected ({f.masked}). {f.remediation}"
|
|
49
|
+
if f.context_path:
|
|
50
|
+
msg = f"[{f.context_path}] {msg}"
|
|
51
|
+
sarif_results.append(
|
|
52
|
+
{
|
|
53
|
+
"ruleId": f.rule_id,
|
|
54
|
+
"level": f.severity,
|
|
55
|
+
"message": {"text": msg},
|
|
56
|
+
"locations": [
|
|
57
|
+
{
|
|
58
|
+
"physicalLocation": {
|
|
59
|
+
"artifactLocation": {"uri": f.file},
|
|
60
|
+
"region": {
|
|
61
|
+
"startLine": max(1, f.line),
|
|
62
|
+
"startColumn": max(1, f.column),
|
|
63
|
+
},
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
],
|
|
67
|
+
}
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
return {
|
|
71
|
+
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
|
|
72
|
+
"version": "2.1.0",
|
|
73
|
+
"runs": [
|
|
74
|
+
{
|
|
75
|
+
"tool": {
|
|
76
|
+
"driver": {
|
|
77
|
+
"name": "llm-keyguard",
|
|
78
|
+
"version": version,
|
|
79
|
+
"informationUri": "https://pypi.org/project/llm-keyguard/",
|
|
80
|
+
"rules": rule_catalog,
|
|
81
|
+
}
|
|
82
|
+
},
|
|
83
|
+
"results": sarif_results,
|
|
84
|
+
}
|
|
85
|
+
],
|
|
86
|
+
}
|
llm_keyguard/scanner.py
ADDED
|
@@ -0,0 +1,341 @@
|
|
|
1
|
+
"""Core file, Git diff/history, and MCP configuration scanners."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import os
|
|
7
|
+
import subprocess
|
|
8
|
+
from dataclasses import asdict, dataclass
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import Any, Dict, Iterable, List, Optional, Sequence, Set
|
|
11
|
+
|
|
12
|
+
from .signatures import (
|
|
13
|
+
INLINE_IGNORE_MARKERS,
|
|
14
|
+
RULES,
|
|
15
|
+
is_likely_placeholder,
|
|
16
|
+
mask_secret,
|
|
17
|
+
shannon_entropy,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
SCANNABLE_EXTENSIONS: Set[str] = {
|
|
21
|
+
".py", ".pyi", ".ipynb", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
|
|
22
|
+
".json", ".jsonc", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".conf",
|
|
23
|
+
".sh", ".bash", ".zsh", ".ps1", ".bat", ".cmd", ".rb", ".go", ".rs",
|
|
24
|
+
".java", ".kt", ".cs", ".php", ".swift", ".md", ".txt", ".env",
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
DEFAULT_SKIP_DIRS: Set[str] = {
|
|
28
|
+
".git", "node_modules", "__pycache__", ".pytest_cache", ".mypy_cache",
|
|
29
|
+
".ruff_cache", ".venv", "venv", "env", ".tox", "dist", "build", ".next",
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
MCP_CONFIG_FILENAMES: Set[str] = {
|
|
33
|
+
"mcp.json",
|
|
34
|
+
".mcp.json",
|
|
35
|
+
"mcp_config.json",
|
|
36
|
+
"claude_desktop_config.json",
|
|
37
|
+
"cline_mcp_settings.json",
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
SENSITIVE_ENV_KEY_HINTS = (
|
|
41
|
+
"api_key", "apikey", "secret", "token", "password", "passwd", "private_key", "access_key",
|
|
42
|
+
)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
@dataclass(frozen=True)
|
|
46
|
+
class Finding:
|
|
47
|
+
"""Single verified secret or credential policy violation."""
|
|
48
|
+
|
|
49
|
+
rule_id: str
|
|
50
|
+
provider: str
|
|
51
|
+
severity: str
|
|
52
|
+
file: str
|
|
53
|
+
line: int
|
|
54
|
+
column: int
|
|
55
|
+
masked: str
|
|
56
|
+
entropy: float
|
|
57
|
+
remediation: str
|
|
58
|
+
context_path: str = ""
|
|
59
|
+
|
|
60
|
+
def to_dict(self) -> Dict[str, Any]:
|
|
61
|
+
return asdict(self)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def is_dotenv_secret_file(path: Path) -> bool:
|
|
65
|
+
"""Return True if path is a live .env file (excluding safe templates like .env.example)."""
|
|
66
|
+
name = path.name.lower()
|
|
67
|
+
if name in {".env.example", ".env.sample", ".env.template", ".env.schema"}:
|
|
68
|
+
return False
|
|
69
|
+
return name == ".env" or name.startswith(".env.")
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def scan_text(
|
|
73
|
+
text: str,
|
|
74
|
+
file_label: str = "<memory>",
|
|
75
|
+
extra_ignore_patterns: Optional[Sequence[str]] = None,
|
|
76
|
+
) -> List[Finding]:
|
|
77
|
+
"""Scan raw text line-by-line and return verified secret findings."""
|
|
78
|
+
findings: List[Finding] = []
|
|
79
|
+
for line_idx, line in enumerate(text.splitlines(), start=1):
|
|
80
|
+
if len(line) > 8192:
|
|
81
|
+
continue
|
|
82
|
+
low_line = line.lower()
|
|
83
|
+
if any(marker in low_line for marker in INLINE_IGNORE_MARKERS):
|
|
84
|
+
continue
|
|
85
|
+
for rule in RULES:
|
|
86
|
+
for match in rule.pattern.finditer(line):
|
|
87
|
+
candidate = match.group(0)
|
|
88
|
+
if is_likely_placeholder(candidate):
|
|
89
|
+
continue
|
|
90
|
+
if extra_ignore_patterns and any(pat in candidate for pat in extra_ignore_patterns):
|
|
91
|
+
continue
|
|
92
|
+
ent = shannon_entropy(candidate)
|
|
93
|
+
if ent < rule.min_entropy:
|
|
94
|
+
continue
|
|
95
|
+
findings.append(
|
|
96
|
+
Finding(
|
|
97
|
+
rule_id=rule.rule_id,
|
|
98
|
+
provider=rule.provider,
|
|
99
|
+
severity=rule.severity,
|
|
100
|
+
file=file_label,
|
|
101
|
+
line=line_idx,
|
|
102
|
+
column=match.start() + 1,
|
|
103
|
+
masked=mask_secret(candidate),
|
|
104
|
+
entropy=round(ent, 2),
|
|
105
|
+
remediation=rule.remediation,
|
|
106
|
+
)
|
|
107
|
+
)
|
|
108
|
+
return findings
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def scan_file(
|
|
112
|
+
path: Path,
|
|
113
|
+
include_dotenv: bool = False,
|
|
114
|
+
max_bytes: int = 3_000_000,
|
|
115
|
+
) -> List[Finding]:
|
|
116
|
+
"""Scan a single file on disk."""
|
|
117
|
+
if not path.is_file():
|
|
118
|
+
return []
|
|
119
|
+
if is_dotenv_secret_file(path) and not include_dotenv:
|
|
120
|
+
return []
|
|
121
|
+
suffix = path.suffix.lower()
|
|
122
|
+
if suffix not in SCANNABLE_EXTENSIONS and path.name not in MCP_CONFIG_FILENAMES:
|
|
123
|
+
return []
|
|
124
|
+
try:
|
|
125
|
+
if path.stat().st_size > max_bytes:
|
|
126
|
+
return []
|
|
127
|
+
content = path.read_text(encoding="utf-8", errors="ignore")
|
|
128
|
+
except OSError:
|
|
129
|
+
return []
|
|
130
|
+
return scan_text(content, file_label=path.as_posix())
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def iter_files(root: Path, skip_dirs: Optional[Set[str]] = None) -> Iterable[Path]:
|
|
134
|
+
"""Yield files recursively while pruning ignored build/dependency directories."""
|
|
135
|
+
if root.is_file():
|
|
136
|
+
yield root
|
|
137
|
+
return
|
|
138
|
+
excluded = skip_dirs if skip_dirs is not None else DEFAULT_SKIP_DIRS
|
|
139
|
+
for dirpath, dirnames, filenames in os.walk(root):
|
|
140
|
+
dirnames[:] = [d for d in dirnames if d not in excluded]
|
|
141
|
+
base = Path(dirpath)
|
|
142
|
+
for fname in sorted(filenames):
|
|
143
|
+
yield base / fname
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def scan_path(root: Path, include_dotenv: bool = False) -> List[Finding]:
|
|
147
|
+
"""Scan a directory tree or single file for hardcoded secrets and MCP leaks."""
|
|
148
|
+
results: List[Finding] = []
|
|
149
|
+
seen_keys: Set[tuple] = set()
|
|
150
|
+
for file_path in iter_files(root):
|
|
151
|
+
for f in scan_file(file_path, include_dotenv=include_dotenv):
|
|
152
|
+
dedup = (f.file, f.line, f.column, f.rule_id)
|
|
153
|
+
if dedup not in seen_keys:
|
|
154
|
+
seen_keys.add(dedup)
|
|
155
|
+
results.append(f)
|
|
156
|
+
if _looks_like_mcp_config(file_path):
|
|
157
|
+
for mf in audit_mcp_file(file_path):
|
|
158
|
+
dedup = (mf.file, mf.line, mf.rule_id, mf.context_path)
|
|
159
|
+
if dedup not in seen_keys:
|
|
160
|
+
seen_keys.add(dedup)
|
|
161
|
+
results.append(mf)
|
|
162
|
+
return results
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def _looks_like_mcp_config(path: Path) -> bool:
|
|
166
|
+
name = path.name.lower()
|
|
167
|
+
if name in MCP_CONFIG_FILENAMES:
|
|
168
|
+
return True
|
|
169
|
+
parts = {p.lower() for p in path.parts}
|
|
170
|
+
return name == "mcp.json" or (".cursor" in parts and name.endswith(".json"))
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def _walk_json_secrets(
|
|
174
|
+
node: Any,
|
|
175
|
+
key_path: str,
|
|
176
|
+
file_label: str,
|
|
177
|
+
raw_lines: List[str],
|
|
178
|
+
out: List[Finding],
|
|
179
|
+
) -> None:
|
|
180
|
+
if isinstance(node, dict):
|
|
181
|
+
for k, v in node.items():
|
|
182
|
+
sub_path = f"{key_path}.{k}" if key_path else str(k)
|
|
183
|
+
_walk_json_secrets(v, sub_path, file_label, raw_lines, out)
|
|
184
|
+
elif isinstance(node, list):
|
|
185
|
+
for idx, item in enumerate(node):
|
|
186
|
+
_walk_json_secrets(item, f"{key_path}[{idx}]", file_label, raw_lines, out)
|
|
187
|
+
elif isinstance(node, str):
|
|
188
|
+
val = node.strip()
|
|
189
|
+
if not val or val.startswith("${") or val.startswith("$env:") or val.startswith("<"):
|
|
190
|
+
return
|
|
191
|
+
leaf_key = key_path.rsplit(".", 1)[-1].lower()
|
|
192
|
+
is_sensitive_key = any(h in leaf_key for h in SENSITIVE_ENV_KEY_HINTS)
|
|
193
|
+
# Check known provider signatures first
|
|
194
|
+
direct = scan_text(val, file_label=file_label)
|
|
195
|
+
line_no = _locate_line_number(raw_lines, val)
|
|
196
|
+
if direct:
|
|
197
|
+
for d in direct:
|
|
198
|
+
out.append(
|
|
199
|
+
Finding(
|
|
200
|
+
rule_id="LLMKG101",
|
|
201
|
+
provider=f"MCP Config Hardcoded {d.provider}",
|
|
202
|
+
severity="error",
|
|
203
|
+
file=file_label,
|
|
204
|
+
line=line_no,
|
|
205
|
+
column=1,
|
|
206
|
+
masked=d.masked,
|
|
207
|
+
entropy=d.entropy,
|
|
208
|
+
remediation=f"Replace literal in '{key_path}' with '${{env:{leaf_key.upper()}}}' or OS env injection.",
|
|
209
|
+
context_path=key_path,
|
|
210
|
+
)
|
|
211
|
+
)
|
|
212
|
+
elif is_sensitive_key and len(val) >= 16 and not is_likely_placeholder(val):
|
|
213
|
+
ent = shannon_entropy(val)
|
|
214
|
+
if ent >= 3.50:
|
|
215
|
+
out.append(
|
|
216
|
+
Finding(
|
|
217
|
+
rule_id="LLMKG102",
|
|
218
|
+
provider="MCP Config High-Entropy Credential",
|
|
219
|
+
severity="error",
|
|
220
|
+
file=file_label,
|
|
221
|
+
line=line_no,
|
|
222
|
+
column=1,
|
|
223
|
+
masked=mask_secret(val),
|
|
224
|
+
entropy=round(ent, 2),
|
|
225
|
+
remediation=f"Avoid committing literal credentials in '{key_path}'; reference an environment variable.",
|
|
226
|
+
context_path=key_path,
|
|
227
|
+
)
|
|
228
|
+
)
|
|
229
|
+
|
|
230
|
+
|
|
231
|
+
def _locate_line_number(lines: List[str], needle: str) -> int:
|
|
232
|
+
short_needle = needle[:24]
|
|
233
|
+
for idx, ln in enumerate(lines, start=1):
|
|
234
|
+
if short_needle in ln:
|
|
235
|
+
return idx
|
|
236
|
+
return 1
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
def audit_mcp_file(path: Path) -> List[Finding]:
|
|
240
|
+
"""Parse an MCP configuration JSON file and detect hardcoded server credentials."""
|
|
241
|
+
try:
|
|
242
|
+
raw = path.read_text(encoding="utf-8", errors="ignore")
|
|
243
|
+
parsed = json.loads(raw)
|
|
244
|
+
except Exception:
|
|
245
|
+
return []
|
|
246
|
+
findings: List[Finding] = []
|
|
247
|
+
_walk_json_secrets(parsed, "", path.as_posix(), raw.splitlines(), findings)
|
|
248
|
+
return findings
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def audit_mcp_configs(root: Path) -> List[Finding]:
|
|
252
|
+
"""Find and audit all MCP configuration files under root."""
|
|
253
|
+
out: List[Finding] = []
|
|
254
|
+
for fp in iter_files(root):
|
|
255
|
+
if _looks_like_mcp_config(fp):
|
|
256
|
+
out.extend(audit_mcp_file(fp))
|
|
257
|
+
return out
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def scan_git_staged(repo_dir: Path) -> List[Finding]:
|
|
261
|
+
"""Scan files currently staged in Git (`git diff --cached`) and block staged .env files."""
|
|
262
|
+
proc = subprocess.run(
|
|
263
|
+
["git", "diff", "--cached", "--name-only", "--diff-filter=ACMR"],
|
|
264
|
+
cwd=str(repo_dir),
|
|
265
|
+
capture_output=True,
|
|
266
|
+
text=True,
|
|
267
|
+
check=False,
|
|
268
|
+
)
|
|
269
|
+
if proc.returncode != 0:
|
|
270
|
+
return []
|
|
271
|
+
|
|
272
|
+
findings: List[Finding] = []
|
|
273
|
+
for rel in proc.stdout.splitlines():
|
|
274
|
+
rel_clean = rel.strip()
|
|
275
|
+
if not rel_clean:
|
|
276
|
+
continue
|
|
277
|
+
full_path = repo_dir / rel_clean
|
|
278
|
+
if is_dotenv_secret_file(full_path):
|
|
279
|
+
findings.append(
|
|
280
|
+
Finding(
|
|
281
|
+
rule_id="LLMKG000",
|
|
282
|
+
provider="Staged .env File",
|
|
283
|
+
severity="error",
|
|
284
|
+
file=full_path.as_posix(),
|
|
285
|
+
line=1,
|
|
286
|
+
column=1,
|
|
287
|
+
masked=full_path.name,
|
|
288
|
+
entropy=0.0,
|
|
289
|
+
remediation="Unstage with `git restore --staged .env` and add `.env` to `.gitignore`.",
|
|
290
|
+
)
|
|
291
|
+
)
|
|
292
|
+
continue
|
|
293
|
+
findings.extend(scan_file(full_path, include_dotenv=True))
|
|
294
|
+
if _looks_like_mcp_config(full_path):
|
|
295
|
+
findings.extend(audit_mcp_file(full_path))
|
|
296
|
+
return findings
|
|
297
|
+
|
|
298
|
+
|
|
299
|
+
def scan_git_history(repo_dir: Path, max_commits: int = 50) -> List[Finding]:
|
|
300
|
+
"""Scan recent Git commit patches (`git log -p`) for historically leaked keys."""
|
|
301
|
+
proc = subprocess.run(
|
|
302
|
+
["git", "log", f"-n{int(max_commits)}", "-p", "--no-color"],
|
|
303
|
+
cwd=str(repo_dir),
|
|
304
|
+
capture_output=True,
|
|
305
|
+
text=True,
|
|
306
|
+
encoding="utf-8",
|
|
307
|
+
errors="ignore",
|
|
308
|
+
check=False,
|
|
309
|
+
)
|
|
310
|
+
if proc.returncode != 0 or not proc.stdout:
|
|
311
|
+
return []
|
|
312
|
+
|
|
313
|
+
findings: List[Finding] = []
|
|
314
|
+
current_commit = "HEAD"
|
|
315
|
+
current_file = "<git-log>"
|
|
316
|
+
added_line_no = 0
|
|
317
|
+
|
|
318
|
+
for line in proc.stdout.splitlines():
|
|
319
|
+
if line.startswith("commit "):
|
|
320
|
+
current_commit = line.split()[1][:10]
|
|
321
|
+
elif line.startswith("+++ b/"):
|
|
322
|
+
current_file = f"{line[6:]}@{current_commit}"
|
|
323
|
+
added_line_no = 0
|
|
324
|
+
elif line.startswith("+") and not line.startswith("+++"):
|
|
325
|
+
added_line_no += 1
|
|
326
|
+
for hit in scan_text(line[1:], file_label=current_file):
|
|
327
|
+
findings.append(
|
|
328
|
+
Finding(
|
|
329
|
+
rule_id=hit.rule_id,
|
|
330
|
+
provider=hit.provider,
|
|
331
|
+
severity=hit.severity,
|
|
332
|
+
file=current_file,
|
|
333
|
+
line=added_line_no,
|
|
334
|
+
column=hit.column,
|
|
335
|
+
masked=hit.masked,
|
|
336
|
+
entropy=hit.entropy,
|
|
337
|
+
remediation=hit.remediation,
|
|
338
|
+
context_path=f"commit:{current_commit}",
|
|
339
|
+
)
|
|
340
|
+
)
|
|
341
|
+
return findings
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
"""Provider secret signatures and entropy helpers for llm-keyguard."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import math
|
|
6
|
+
import re
|
|
7
|
+
from collections import Counter
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
from typing import List, Pattern
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
@dataclass(frozen=True)
|
|
13
|
+
class SecretRule:
|
|
14
|
+
"""Compiled detection rule for a specific AI, cloud, or developer token format."""
|
|
15
|
+
|
|
16
|
+
rule_id: str
|
|
17
|
+
provider: str
|
|
18
|
+
severity: str
|
|
19
|
+
pattern: Pattern[str]
|
|
20
|
+
min_entropy: float
|
|
21
|
+
remediation: str
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
RULES: List[SecretRule] = [
|
|
25
|
+
SecretRule(
|
|
26
|
+
rule_id="LLMKG001",
|
|
27
|
+
provider="OpenAI API Key (Project/Service/Admin)",
|
|
28
|
+
severity="error",
|
|
29
|
+
pattern=re.compile(r"\bsk-(?:proj|svcacct|admin)-[0-9A-Za-z_\-]{32,}\b"),
|
|
30
|
+
min_entropy=3.75,
|
|
31
|
+
remediation="Move to OPENAI_API_KEY in .env and revoke leaked key at platform.openai.com/api-keys.",
|
|
32
|
+
),
|
|
33
|
+
SecretRule(
|
|
34
|
+
rule_id="LLMKG002",
|
|
35
|
+
provider="OpenAI Legacy Secret Key",
|
|
36
|
+
severity="error",
|
|
37
|
+
pattern=re.compile(r"\bsk-[0-9A-Za-z]{20}T3BlbkFJ[0-9A-Za-z]{20}\b"),
|
|
38
|
+
min_entropy=3.80,
|
|
39
|
+
remediation="Rotate legacy OpenAI key immediately and switch to scoped project keys.",
|
|
40
|
+
),
|
|
41
|
+
SecretRule(
|
|
42
|
+
rule_id="LLMKG003",
|
|
43
|
+
provider="Anthropic Claude API Key",
|
|
44
|
+
severity="error",
|
|
45
|
+
pattern=re.compile(r"\bsk-ant-(?:api\d+-)?[0-9A-Za-z_\-]{36,}\b"),
|
|
46
|
+
min_entropy=3.80,
|
|
47
|
+
remediation="Move to ANTHROPIC_API_KEY in .env and rotate in Anthropic Console.",
|
|
48
|
+
),
|
|
49
|
+
SecretRule(
|
|
50
|
+
rule_id="LLMKG004",
|
|
51
|
+
provider="Google Gemini / Cloud API Key",
|
|
52
|
+
severity="error",
|
|
53
|
+
pattern=re.compile(r"\bAIzaSy[0-9A-Za-z_\-]{33}\b"),
|
|
54
|
+
min_entropy=3.60,
|
|
55
|
+
remediation="Move to GEMINI_API_KEY in .env and restrict/rotate key in Google AI Studio or GCP.",
|
|
56
|
+
),
|
|
57
|
+
SecretRule(
|
|
58
|
+
rule_id="LLMKG005",
|
|
59
|
+
provider="Groq API Key",
|
|
60
|
+
severity="error",
|
|
61
|
+
pattern=re.compile(r"\bgsk_[0-9A-Za-z]{40,}\b"),
|
|
62
|
+
min_entropy=3.80,
|
|
63
|
+
remediation="Move to GROQ_API_KEY in .env and revoke in GroqCloud Console.",
|
|
64
|
+
),
|
|
65
|
+
SecretRule(
|
|
66
|
+
rule_id="LLMKG006",
|
|
67
|
+
provider="OpenRouter API Key",
|
|
68
|
+
severity="error",
|
|
69
|
+
pattern=re.compile(r"\bsk-or-v1-[0-9A-Za-z]{48,}\b"),
|
|
70
|
+
min_entropy=3.45,
|
|
71
|
+
remediation="Move to OPENROUTER_API_KEY in .env and revoke at openrouter.ai/keys.",
|
|
72
|
+
),
|
|
73
|
+
SecretRule(
|
|
74
|
+
rule_id="LLMKG007",
|
|
75
|
+
provider="HuggingFace Access Token",
|
|
76
|
+
severity="error",
|
|
77
|
+
pattern=re.compile(r"\bhf_[0-9A-Za-z]{30,}\b"),
|
|
78
|
+
min_entropy=3.60,
|
|
79
|
+
remediation="Move to HF_TOKEN in .env and invalidate token at huggingface.co/settings/tokens.",
|
|
80
|
+
),
|
|
81
|
+
SecretRule(
|
|
82
|
+
rule_id="LLMKG008",
|
|
83
|
+
provider="Replicate API Token",
|
|
84
|
+
severity="error",
|
|
85
|
+
pattern=re.compile(r"\br8_[0-9A-Za-z]{34,}\b"),
|
|
86
|
+
min_entropy=3.65,
|
|
87
|
+
remediation="Move to REPLICATE_API_TOKEN in .env and rotate on replicate.com.",
|
|
88
|
+
),
|
|
89
|
+
SecretRule(
|
|
90
|
+
rule_id="LLMKG009",
|
|
91
|
+
provider="Perplexity Sonar API Key",
|
|
92
|
+
severity="error",
|
|
93
|
+
pattern=re.compile(r"\bpplx-[0-9A-Za-z]{40,}\b"),
|
|
94
|
+
min_entropy=3.65,
|
|
95
|
+
remediation="Move to PERPLEXITY_API_KEY in .env and rotate in Perplexity API settings.",
|
|
96
|
+
),
|
|
97
|
+
SecretRule(
|
|
98
|
+
rule_id="LLMKG010",
|
|
99
|
+
provider="Fireworks AI API Key",
|
|
100
|
+
severity="error",
|
|
101
|
+
pattern=re.compile(r"\bfw_[0-9A-Za-z]{24,}\b"),
|
|
102
|
+
min_entropy=3.60,
|
|
103
|
+
remediation="Move to FIREWORKS_API_KEY in .env and rotate at fireworks.ai.",
|
|
104
|
+
),
|
|
105
|
+
SecretRule(
|
|
106
|
+
rule_id="LLMKG011",
|
|
107
|
+
provider="Tavily Search API Key",
|
|
108
|
+
severity="error",
|
|
109
|
+
pattern=re.compile(r"\btvly-(?:dev-|prod-)?[0-9A-Za-z]{28,}\b"),
|
|
110
|
+
min_entropy=3.60,
|
|
111
|
+
remediation="Move to TAVILY_API_KEY in .env and rotate in Tavily dashboard.",
|
|
112
|
+
),
|
|
113
|
+
SecretRule(
|
|
114
|
+
rule_id="LLMKG012",
|
|
115
|
+
provider="Pinecone Vector DB Key",
|
|
116
|
+
severity="error",
|
|
117
|
+
pattern=re.compile(r"\bpcsk_[0-9A-Za-z_]{40,}\b"),
|
|
118
|
+
min_entropy=3.70,
|
|
119
|
+
remediation="Move to PINECONE_API_KEY in .env and rotate in Pinecone Console.",
|
|
120
|
+
),
|
|
121
|
+
SecretRule(
|
|
122
|
+
rule_id="LLMKG013",
|
|
123
|
+
provider="LangSmith / LangChain API Key",
|
|
124
|
+
severity="error",
|
|
125
|
+
pattern=re.compile(r"\blsv2_(?:pt|sk)_[0-9A-Za-z_]{32,}\b"),
|
|
126
|
+
min_entropy=3.60,
|
|
127
|
+
remediation="Move to LANGSMITH_API_KEY in .env and revoke in LangSmith.",
|
|
128
|
+
),
|
|
129
|
+
SecretRule(
|
|
130
|
+
rule_id="LLMKG014",
|
|
131
|
+
provider="ElevenLabs API Key",
|
|
132
|
+
severity="error",
|
|
133
|
+
pattern=re.compile(r"\bsk_[0-9a-f]{48}\b"),
|
|
134
|
+
min_entropy=3.55,
|
|
135
|
+
remediation="Move to ELEVENLABS_API_KEY in .env and rotate in ElevenLabs profile.",
|
|
136
|
+
),
|
|
137
|
+
SecretRule(
|
|
138
|
+
rule_id="LLMKG015",
|
|
139
|
+
provider="Supabase Access Token",
|
|
140
|
+
severity="error",
|
|
141
|
+
pattern=re.compile(r"\bsbp_[0-9a-f]{40}\b"),
|
|
142
|
+
min_entropy=3.55,
|
|
143
|
+
remediation="Move to SUPABASE_ACCESS_TOKEN in .env and revoke in Supabase account.",
|
|
144
|
+
),
|
|
145
|
+
SecretRule(
|
|
146
|
+
rule_id="LLMKG016",
|
|
147
|
+
provider="GitHub Personal Access Token",
|
|
148
|
+
severity="error",
|
|
149
|
+
pattern=re.compile(r"\b(?:gh[pousr]_[0-9A-Za-z]{36,}|github_pat_[0-9A-Za-z_]{50,})\b"),
|
|
150
|
+
min_entropy=3.70,
|
|
151
|
+
remediation="Revoke token immediately at github.com/settings/tokens.",
|
|
152
|
+
),
|
|
153
|
+
SecretRule(
|
|
154
|
+
rule_id="LLMKG017",
|
|
155
|
+
provider="AWS Access Key ID",
|
|
156
|
+
severity="error",
|
|
157
|
+
pattern=re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b"),
|
|
158
|
+
min_entropy=3.25,
|
|
159
|
+
remediation="Deactivate AWS IAM key in AWS Console and switch to IAM roles/OIDC.",
|
|
160
|
+
),
|
|
161
|
+
SecretRule(
|
|
162
|
+
rule_id="LLMKG018",
|
|
163
|
+
provider="Stripe Live Secret Key",
|
|
164
|
+
severity="error",
|
|
165
|
+
pattern=re.compile(r"\b(?:sk|rk)_live_[0-9A-Za-z]{24,}\b"),
|
|
166
|
+
min_entropy=3.65,
|
|
167
|
+
remediation="Roll live Stripe key immediately in Stripe Dashboard.",
|
|
168
|
+
),
|
|
169
|
+
SecretRule(
|
|
170
|
+
rule_id="LLMKG019",
|
|
171
|
+
provider="Slack Bot / User Token",
|
|
172
|
+
severity="error",
|
|
173
|
+
pattern=re.compile(r"\bxox[baprs]-[0-9A-Za-z\-]{24,}\b"),
|
|
174
|
+
min_entropy=3.55,
|
|
175
|
+
remediation="Revoke Slack token in Slack App Management.",
|
|
176
|
+
),
|
|
177
|
+
SecretRule(
|
|
178
|
+
rule_id="LLMKG020",
|
|
179
|
+
provider="Private Cryptographic Key Block",
|
|
180
|
+
severity="error",
|
|
181
|
+
pattern=re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----"),
|
|
182
|
+
min_entropy=2.40,
|
|
183
|
+
remediation="Remove private key file from repository and rotate keypair.",
|
|
184
|
+
),
|
|
185
|
+
]
|
|
186
|
+
|
|
187
|
+
PLACEHOLDER_SUBSTRINGS = (
|
|
188
|
+
"your_",
|
|
189
|
+
"your-",
|
|
190
|
+
"example",
|
|
191
|
+
"xxx",
|
|
192
|
+
"00000000",
|
|
193
|
+
"12345678",
|
|
194
|
+
"abcdef012345",
|
|
195
|
+
"replace_me",
|
|
196
|
+
"changeme",
|
|
197
|
+
"placeholder",
|
|
198
|
+
"dummy",
|
|
199
|
+
"sample_",
|
|
200
|
+
"test_key",
|
|
201
|
+
"fake_key",
|
|
202
|
+
)
|
|
203
|
+
|
|
204
|
+
INLINE_IGNORE_MARKERS = ("keyguard: ignore", "keyguard:ignore", "pragma: allowlist secret")
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def shannon_entropy(value: str) -> float:
|
|
208
|
+
"""Compute Shannon entropy in bits per character."""
|
|
209
|
+
if not value:
|
|
210
|
+
return 0.0
|
|
211
|
+
counts = Counter(value)
|
|
212
|
+
length = float(len(value))
|
|
213
|
+
return -sum((count / length) * math.log2(count / length) for count in counts.values())
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
def is_likely_placeholder(value: str) -> bool:
|
|
217
|
+
"""Return True if a matched string looks like documentation or a test placeholder."""
|
|
218
|
+
low = value.lower()
|
|
219
|
+
if any(token in low for token in PLACEHOLDER_SUBSTRINGS):
|
|
220
|
+
return True
|
|
221
|
+
# Reject highly repetitive synthetic strings such as sk-proj-aaaaaaaaaaaaaaaaaaaaaaaaaaaa
|
|
222
|
+
unique_ratio = len(set(value)) / max(1, len(value))
|
|
223
|
+
return unique_ratio < 0.22
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def mask_secret(value: str) -> str:
|
|
227
|
+
"""Mask a secret safely for terminal and CI logs without leaking raw credentials."""
|
|
228
|
+
if len(value) <= 12:
|
|
229
|
+
return "***REDACTED***"
|
|
230
|
+
return f"{value[:6]}...{value[-4:]} (len={len(value)})"
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: llm-keyguard
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Zero-dependency secret scanner, MCP config auditor, and Git pre-commit guard for LLM & AI API keys.
|
|
5
|
+
License: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/Edimilson22/llm-keyguard
|
|
7
|
+
Project-URL: Repository, https://github.com/Edimilson22/llm-keyguard
|
|
8
|
+
Project-URL: Issues, https://github.com/Edimilson22/llm-keyguard/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/Edimilson22/llm-keyguard/blob/main/CHANGELOG.md
|
|
10
|
+
Keywords: security,secrets,pre-commit,llm,openai,anthropic,mcp,api-keys,sarif,devsecops
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Security
|
|
23
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
24
|
+
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.9
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
31
|
+
Requires-Dist: build>=1.0; extra == "dev"
|
|
32
|
+
Requires-Dist: twine>=5.0; extra == "dev"
|
|
33
|
+
Dynamic: license-file
|
|
34
|
+
|
|
35
|
+
# llm-keyguard
|
|
36
|
+
|
|
37
|
+
**Zero-dependency secret scanner, MCP configuration auditor, and `<35ms` Git pre-commit guard for LLM & AI API keys.**
|
|
38
|
+
|
|
39
|
+
Modern AI engineering introduces new credential leak vectors beyond traditional web apps: developers frequently commit `.mcp.json`, `.cursor/mcp.json`, Jupyter notebooks, and agent configuration files containing live keys for OpenAI, Anthropic, Gemini, Groq, OpenRouter, Pinecone, LangSmith, HuggingFace, and ElevenLabs.
|
|
40
|
+
|
|
41
|
+
`llm-keyguard` is a pure-Python, zero-dependency CLI and library designed to stop AI credential leaks before they enter Git history—without requiring external Go binaries or Docker containers.
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Features
|
|
46
|
+
|
|
47
|
+
- **20+ AI, Vector DB & Cloud Signatures + Shannon Entropy Filtering:** Detects OpenAI (`sk-proj-`, `sk-svcacct-`, `sk-admin-`), Anthropic (`sk-ant-`), Google Gemini (`AIzaSy`), Groq (`gsk_`), OpenRouter (`sk-or-v1-`), HuggingFace (`hf_`), Replicate (`r8_`), Perplexity (`pplx-`), Fireworks (`fw_`), Tavily (`tvly-`), Pinecone (`pcsk_`), LangSmith (`lsv2_`), ElevenLabs, Supabase, GitHub PATs, AWS IAM, Stripe Live, Slack, and PEM private keys while ignoring low-entropy placeholders.
|
|
48
|
+
- **Dedicated MCP Config Auditor (`audit-mcp`):** Parses `mcp.json`, `.mcp.json`, `.cursor/mcp.json`, and `claude_desktop_config.json` to pinpoint exact JSON paths (e.g. `mcpServers.search.env.OPENAI_API_KEY`) containing literal credentials instead of environment references.
|
|
49
|
+
- **One-Command Repository Hardening (`init`):** Automatically hardens `.gitignore` (blocking `.env` and key files while allowing `.env.example`) and installs a fast native Git `pre-commit` hook.
|
|
50
|
+
- **Safe `.env.example` Generator (`env-example`):** Generates sanitized `.env.example` templates from local `.env` files without exposing real credentials.
|
|
51
|
+
- **OASIS SARIF v2.1.0 Export (`--format sarif`):** Integrates directly with GitHub Code Scanning and CI pipelines.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Quickstart
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pip install llm-keyguard
|
|
59
|
+
|
|
60
|
+
# 1. Harden .gitignore and install the Git pre-commit guard
|
|
61
|
+
llm-keyguard init
|
|
62
|
+
|
|
63
|
+
# 2. Scan your project directory (including MCP configs)
|
|
64
|
+
llm-keyguard scan .
|
|
65
|
+
|
|
66
|
+
# 3. Audit MCP configuration files specifically
|
|
67
|
+
llm-keyguard audit-mcp .
|
|
68
|
+
|
|
69
|
+
# 4. Generate a safe .env.example from your local .env
|
|
70
|
+
llm-keyguard env-example --source .env --output .env.example
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Using with `pre-commit`
|
|
76
|
+
|
|
77
|
+
Add `llm-keyguard` to your `.pre-commit-config.yaml`:
|
|
78
|
+
|
|
79
|
+
```yaml
|
|
80
|
+
repos:
|
|
81
|
+
- repo: https://github.com/Edimilson22/llm-keyguard
|
|
82
|
+
rev: v0.2.0
|
|
83
|
+
hooks:
|
|
84
|
+
- id: llm-keyguard
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## GitHub Actions & Code Scanning (SARIF)
|
|
90
|
+
|
|
91
|
+
```yaml
|
|
92
|
+
name: AI Credential Scan
|
|
93
|
+
on: [push, pull_request]
|
|
94
|
+
|
|
95
|
+
jobs:
|
|
96
|
+
keyguard:
|
|
97
|
+
runs-on: ubuntu-latest
|
|
98
|
+
permissions:
|
|
99
|
+
security-events: write
|
|
100
|
+
contents: read
|
|
101
|
+
steps:
|
|
102
|
+
- uses: actions/checkout@v4
|
|
103
|
+
- uses: actions/setup-python@v5
|
|
104
|
+
with:
|
|
105
|
+
python-version: "3.12"
|
|
106
|
+
- run: pip install llm-keyguard
|
|
107
|
+
- run: llm-keyguard scan . --format sarif > results.sarif || true
|
|
108
|
+
- uses: github/codeql-action/upload-sarif@v3
|
|
109
|
+
with:
|
|
110
|
+
sarif_file: results.sarif
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## Python API
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
from pathlib import Path
|
|
119
|
+
from llm_keyguard import scan_path, audit_mcp_configs, build_sarif_report
|
|
120
|
+
|
|
121
|
+
findings = scan_path(Path("."))
|
|
122
|
+
for item in findings:
|
|
123
|
+
print(f"[{item.rule_id}] {item.file}:{item.line} -> {item.provider} ({item.masked})")
|
|
124
|
+
|
|
125
|
+
mcp_issues = audit_mcp_configs(Path("."))
|
|
126
|
+
sarif_payload = build_sarif_report(findings)
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Inline Suppression
|
|
132
|
+
|
|
133
|
+
For intentional synthetic test fixtures, append `# keyguard: ignore` (or `# pragma: allowlist secret`) to the line:
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
TEST_FIXTURE = "sk-proj-..." # keyguard: ignore
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## License
|
|
142
|
+
|
|
143
|
+
MIT License. See [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
llm_keyguard/__init__.py,sha256=HLMLd5_RUxDqJDj0jtOMX5COM3k9NUUOF9FB4zX5REo,845
|
|
2
|
+
llm_keyguard/cli.py,sha256=5EoBTMUuh4ZjSrJAcceEfCPGOZfimUAIjyZGRGwSLVE,5737
|
|
3
|
+
llm_keyguard/py.typed,sha256=OHLhUlJwzVblRS88hQOvYv5HXJG8mzugIVr_EYAOCmU,17
|
|
4
|
+
llm_keyguard/remediator.py,sha256=H4Nf-pB4emx7X9ClHz-EpqD8AAtJ7ckPyd9UnZ3oSLg,3412
|
|
5
|
+
llm_keyguard/sarif.py,sha256=C0Aix2sMlVAh_Mmucy_rgT7YDOhsmMqdVeyPHfs0aw0,3072
|
|
6
|
+
llm_keyguard/scanner.py,sha256=JDiQ0yGrmOXeM8qqGDj3fJL3B-ynYDW3h4e8W_l8W_M,11956
|
|
7
|
+
llm_keyguard/signatures.py,sha256=PvDs7Hj76a9zoT3Up_tmLjBPMy-UF235doA1_kS3ZfU,7877
|
|
8
|
+
llm_keyguard-0.2.0.dist-info/licenses/LICENSE,sha256=IYW4EjNadeK34lsTpFCOT9Ev0BqhyCljzJdLaIR6IMY,1082
|
|
9
|
+
llm_keyguard-0.2.0.dist-info/METADATA,sha256=iGTWUZlsfy9tU2QK-3iGPa7C0MO-tf_DmZGQRWtqQ5c,5261
|
|
10
|
+
llm_keyguard-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
11
|
+
llm_keyguard-0.2.0.dist-info/entry_points.txt,sha256=C9-Rwh4VJk0jpQFUdK4Tke3TbJbo-OrF0RKyLpbYQIQ,55
|
|
12
|
+
llm_keyguard-0.2.0.dist-info/top_level.txt,sha256=7halgRCWWkRG5N0JtHoBqBwQ3gMLmWcioFUuH5hO1bs,13
|
|
13
|
+
llm_keyguard-0.2.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 llm-keyguard contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
llm_keyguard
|