@intentsolutionsio/penetration-tester 2.0.0 → 3.0.4

package/skills/detecting-eval-exec-usage/references/THEORY.md

@@ -0,0 +1,159 @@
+# Eval / Exec Theory
+
+## Why this is the highest-impact injection class
+
+SQL injection (skill #11) gives the attacker control over a database
+query. Command injection (skill #12) gives the attacker control over
+a shell process. Eval injection gives the attacker control over the
+application's own interpreter, in the application's own process,
+with the application's own permissions.
+
+There's no privilege boundary between "user-supplied string" and
+"arbitrary code in the application." `eval()` collapses them. Any
+filtering, allow-list, or input validation that the application
+does happens BEFORE the eval; the eval's interpreter sees the
+filtered string and executes it. If the attacker's payload uses
+language constructs the filter didn't anticipate, the filter is
+bypassed by definition.
+
+This is why "don't eval user input" is the only safe rule. There's
+no "but with these escapes it's safe" version.
+
+## When eval seems necessary
+
+Three legitimate use cases drive the temptation:
+
+1. **Formula evaluators.** Spreadsheet-like `=SUM(A1:A5)` cells,
+   custom alerting expressions ("alert when latency > 100ms"),
+   pricing-rule engines.
+
+2. **Plugin systems.** Users supply small scripts that the
+   application runs on their behalf. Examples: Lambda@Edge, Cloudflare
+   Workers, custom log processors.
+
+3. **Configuration as code.** Rare but real: a config file that's
+   actually a Python / JS source file evaluated at startup.
+
+For case 1: use a sandboxed expression library. `simpleeval` for
+Python, `expr-eval` or `mathjs` for JS, `Dentaku` for Ruby. These
+libraries parse a restricted grammar (math + comparison + a curated
+function set) and execute it on a value model that doesn't have
+filesystem / network / process access.
+
+For case 2: run user scripts in a real sandbox: WASM
+(WebAssembly with no system imports), V8 isolate (Node's vm
+module with strict no-globals setup), Lua with stripped-down libs,
+or a containerized worker. Don't run untrusted code in the same
+process as the application.
+
+For case 3: don't. Use JSON/YAML/TOML config. The "config as code"
+flexibility argument is rarely worth the eval-injection surface.
+
+## Why even allow-list filtering fails
+
+A common attempt: "allow only alphanumeric + math operators in the
+evaluated string."
+
+```python
+import re
+if re.match(r"^[\d\+\-\*/\(\)\s\.]+$", user_input):
+    result = eval(user_input)
+```
+
+This looks safe. It's not. Python's eval can:
+
+- Use `__import__` and `__builtins__` accessors via attribute
+  lookup (`().__class__.__bases__[0].__subclasses__()[X]`)
+- Trigger arbitrary code through `__getattr__` on numeric types
+- Call `compile()` on a sub-expression and execute that
+
+Attackers have published "polyglot" payloads that look like pure
+math but reach arbitrary functions via Python's metaprogramming.
+The character-class filter is necessary-but-not-sufficient. The
+ONLY safe approach is a separate interpreter that doesn't have
+access to the language's full surface.
+
+`ast.literal_eval` is safe — it ONLY parses literals (numbers,
+strings, lists, dicts, tuples, booleans, None). No function calls,
+no name references. Use it when you need to evaluate user-supplied
+literal values; don't use it (or anything like it) for
+expression evaluation more generally.
+
+## Per-language safe patterns
+
+### Python — simpleeval for expressions
+
+```python
+from simpleeval import simple_eval
+
+# Safe: only basic math + curated function set
+result = simple_eval("latency * 1.5 + 10", names={"latency": 80})
+```
+
+Or `asteval`:
+
+```python
+from asteval import Interpreter
+aeval = Interpreter()
+result = aeval("a + b * 2", symtable={"a": 1, "b": 2})
+```
+
+### JavaScript — expr-eval
+
+```javascript
+const { Parser } = require('expr-eval');
+const parser = new Parser();
+const expr = parser.parse('latency * 1.5 + 10');
+const result = expr.evaluate({ latency: 80 });
+```
+
+### Ruby — Dentaku
+
+```ruby
+require 'dentaku'
+calc = Dentaku::Calculator.new
+calc.evaluate('latency * 1.5 + 10', latency: 80)
+```
+
+### Java — sandboxed Nashorn / GraalJS
+
+```java
+// GraalJS with restricted permissions
+Context cx = Context.newBuilder("js")
+    .allowHostAccess(HostAccess.NONE)
+    .allowHostClassLookup(name -> false)
+    .build();
+Value result = cx.eval("js", "1 + 2");
+```
+
+## Avoid plugin-system eval
+
+If users need to extend the application with custom logic, the
+right model is:
+
+1. Define a narrow API the plugin can call (e.g., "transform this
+   payload, return a transformed version").
+2. Run the plugin in an isolated sandbox: WASM with no system
+   imports, V8 isolate, separate container, separate language
+   runtime.
+3. Apply timeouts, memory limits, syscall whitelists.
+
+Don't `eval()` the plugin string in the application process. Even
+"trusted" plugin scripts shouldn't have arbitrary access to the
+host application's memory and modules.
+
+## The pickle / serialization overlap
+
+Python `pickle.loads()` is effectively eval-equivalent — pickle can
+execute arbitrary code during deserialization. This is covered in
+depth by skill #14 (`detecting-insecure-deserialization`); this
+skill flags pickle usage as a cross-reference but the remediation
+guidance lives in #14.
+
+## Primary sources
+
+- [CWE-95 Eval Injection](https://cwe.mitre.org/data/definitions/95.html)
+- [Python ast.literal_eval docs](https://docs.python.org/3/library/ast.html#ast.literal_eval)
+- [simpleeval — safe Python expression evaluation](https://github.com/danthedeckie/simpleeval)
+- [Bandit B102 (exec_used) / B307 (eval)](https://bandit.readthedocs.io/en/latest/plugins/b102_exec_used.html)
+- [OWASP Code Review Guide — Dynamic code execution](https://owasp.org/www-project-code-review-guide/)

package/skills/detecting-eval-exec-usage/scripts/scan_eval.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""Static-analysis scan for eval / exec / dynamic-code-execution APIs.
+
+References:
+    CWE-95 Improper Neutralization of Directives in Dynamically Evaluated Code
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+_PLUGIN_ROOT = Path(__file__).resolve().parents[3]
+if str(_PLUGIN_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PLUGIN_ROOT))
+
+from lib.finding import Finding, Severity  # noqa: E402
+from lib.report import emit, exit_code  # noqa: E402
+
+SKILL_ID = "detecting-eval-exec-usage"
+
+PY_PATTERNS = [
+    ("Python eval()", Severity.CRITICAL, r"\beval\s*\(\s*(?!['\"])", "python"),
+    ("Python exec()", Severity.CRITICAL, r"\bexec\s*\(\s*(?!['\"])", "python"),
+    ("Python compile() with non-literal", Severity.HIGH, r"\bcompile\s*\(\s*(?!['\"])", "python"),
+    ("Python __import__ with variable", Severity.HIGH, r"__import__\s*\(\s*(?!['\"])", "python"),
+    (
+        "Python pickle.loads (eval-class deserialization)",
+        Severity.HIGH,
+        r"\bpickle\.loads?\s*\(",
+        "python",
+    ),  # cross-listed; #14 covers in depth
+]
+JS_PATTERNS = [
+    ("JavaScript eval()", Severity.CRITICAL, r"\beval\s*\(", "javascript"),
+    (
+        "JavaScript new Function() with non-literal",
+        Severity.CRITICAL,
+        r"new\s+Function\s*\(\s*(?!['\"`])",
+        "javascript",
+    ),
+    ("JavaScript setTimeout with string arg", Severity.HIGH, r"setTimeout\s*\(\s*['\"`]", "javascript"),
+    ("JavaScript setInterval with string arg", Severity.HIGH, r"setInterval\s*\(\s*['\"`]", "javascript"),
+]
+RUBY_PATTERNS = [
+    ("Ruby eval()", Severity.CRITICAL, r"\beval\s*\(", "ruby"),
+    (
+        "Ruby instance_eval / class_eval with non-block",
+        Severity.HIGH,
+        r"\b(?:instance_eval|class_eval|module_eval)\s*\(\s*['\"]",
+        "ruby",
+    ),
+]
+PHP_PATTERNS = [
+    ("PHP eval()", Severity.CRITICAL, r"\beval\s*\(", "php"),
+    ("PHP assert() with string (legacy eval form)", Severity.CRITICAL, r"\bassert\s*\(\s*['\"$]", "php"),
+    ("PHP create_function (deprecated, eval-equivalent)", Severity.CRITICAL, r"\bcreate_function\s*\(", "php"),
+]
+JAVA_PATTERNS = [
+    ("Java ScriptEngine.eval", Severity.HIGH, r"\bScriptEngine[A-Za-z]*\b.*\.eval\s*\(", "java"),
+    ("Java GroovyShell.evaluate", Severity.HIGH, r"\bGroovyShell\b.*\.evaluate\s*\(", "java"),
+]
+CSHARP_PATTERNS = [
+    (
+        "C# Activator.CreateInstance(Type.GetType(str))",
+        Severity.HIGH,
+        r"Activator\.CreateInstance\s*\(\s*Type\.GetType\s*\(",
+        "csharp",
+    ),
+    ("C# Reflection.Emit", Severity.MEDIUM, r"\bReflection\.Emit\b", "csharp"),
+]
+
+LANG_EXT_MAP = {
+    "python": {".py"},
+    "javascript": {".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx"},
+    "ruby": {".rb"},
+    "php": {".php"},
+    "java": {".java", ".kt", ".scala"},
+    "csharp": {".cs"},
+}
+LANG_PATTERNS = {
+    "python": PY_PATTERNS,
+    "javascript": JS_PATTERNS,
+    "ruby": RUBY_PATTERNS,
+    "php": PHP_PATTERNS,
+    "java": JAVA_PATTERNS,
+    "csharp": CSHARP_PATTERNS,
+}
+SKIP_DIRS = {
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "target",
+    ".cache",
+    ".pnpm-store",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".astro",
+    ".next",
+    ".nuxt",
+    "vendor",
+}
+TEST_DIRS = {"tests", "test", "__tests__", "spec", "specs"}
+MAX_FILE_SIZE = 5 * 1024 * 1024
+
+
+def should_skip_path(path: Path, include_tests: bool) -> bool:
+    parts = set(path.parts)
+    if parts & SKIP_DIRS:
+        return True
+    if not include_tests and parts & TEST_DIRS:
+        return True
+    return False
+
+
+def detect_language(path: Path, langs: set[str]) -> str | None:
+    suf = path.suffix.lower()
+    for lang in langs:
+        if suf in LANG_EXT_MAP[lang]:
+            return lang
+    return None
+
+
+def scan_file(file_path: Path, repo_root: Path, langs: set[str]) -> list[Finding]:
+    findings = []
+    lang = detect_language(file_path, langs)
+    if lang is None:
+        return findings
+    try:
+        if file_path.stat().st_size > MAX_FILE_SIZE:
+            return findings
+        text = file_path.read_text(encoding="utf-8", errors="ignore")
+    except (OSError, ValueError):
+        return findings
+    try:
+        rel = str(file_path.relative_to(repo_root))
+    except ValueError:
+        rel = str(file_path)
+
+    for title, sev, pattern, _lang in LANG_PATTERNS[lang]:
+        for m in re.finditer(pattern, text, re.MULTILINE):
+            line_no = text[: m.start()].count("\n") + 1
+            snippet = text.splitlines()[line_no - 1].strip()[:160]
+            findings.append(
+                Finding(
+                    skill_id=SKILL_ID,
+                    title=f"{title} at {rel}:{line_no}",
+                    severity=sev,
+                    target=f"{rel}:{line_no}",
+                    detail=(
+                        f"File {rel} line {line_no} uses {title}: `{snippet}`. "
+                        "If the evaluated string is user-reachable, this is "
+                        "an arbitrary-code-execution vector."
+                    ),
+                    remediation=(
+                        "Replace dynamic code execution with explicit logic "
+                        "(lookup table, switch statement) or a sandboxed "
+                        "expression library. Python: simpleeval / ast.literal_eval. "
+                        "JS: expr-eval / mathjs. Ruby: Dentaku. See "
+                        "references/PLAYBOOK.md."
+                    ),
+                    cwe_id="CWE-95",
+                    affected_control="OWASP A03:2021",
+                    evidence=(("file", rel), ("line", line_no), ("language", lang), ("snippet", snippet)),
+                )
+            )
+    return findings
+
+
+def walk_repo(root: Path, include_tests: bool, langs: set[str]) -> list[Path]:
+    out = []
+    valid_exts = set()
+    for lang in langs:
+        valid_exts |= LANG_EXT_MAP[lang]
+    for p in root.rglob("*"):
+        if not p.is_file():
+            continue
+        if should_skip_path(p, include_tests):
+            continue
+        if p.suffix.lower() not in valid_exts:
+            continue
+        out.append(p)
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="eval / exec usage scanner")
+    parser.add_argument("path", type=Path)
+    parser.add_argument("--output", default=None)
+    parser.add_argument("--format", choices=("json", "jsonl", "markdown"), default="markdown")
+    parser.add_argument("--min-severity", choices=("critical", "high", "medium", "low", "info"), default="info")
+    parser.add_argument("--include-tests", action="store_true")
+    parser.add_argument("--languages", default="all")
+    args = parser.parse_args(argv)
+
+    if args.languages == "all":
+        langs = set(LANG_PATTERNS.keys())
+    else:
+        langs = {lang.strip() for lang in args.languages.split(",") if lang.strip() in LANG_PATTERNS}
+
+    root = args.path.resolve()
+    if not root.exists():
+        sys.stderr.write(f"ERROR: path does not exist: {root}\n")
+        return 2
+
+    files = walk_repo(root, args.include_tests, langs)
+    findings: list[Finding] = []
+    for f in files:
+        findings.extend(scan_file(f, root, langs))
+
+    floor = Severity(args.min_severity)
+    findings = [f for f in findings if f.severity.numeric >= floor.numeric]
+
+    emit(findings, args.output, args.format, str(root))
+    return exit_code(findings)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/detecting-exposed-secrets-files/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: detecting-exposed-secrets-files
+description: |
+  Probe a target for accidentally-served secret-bearing files in the web root
+  — `.git/`, `.env`, `.DS_Store`, backup files, database dumps, key files,
+  CI configs, IDE configs.
+  Use when: post-deploy verification on a new release, or SOC2 auditor asked
+  "what's reachable in the web root that shouldn't be," or a bug-bounty
+  report hints at a leaked file.
+  Threshold: any of the canonical 40+ paths returns 200 OR returns a body
+  matching the expected fingerprint of the file type (e.g., `.git/HEAD`
+  returns content starting with `ref:` or a 40-char hex SHA).
+  Trigger with: "check exposed files", "git directory exposure",
+  "env file leak", "backup file scan".
+allowed-tools:
+  - Read
+  - Bash(python3:*)
+  - Bash(curl:*)
+disallowed-tools:
+  - Bash(rm:*)
+  - Edit(/etc/*)
+version: 3.0.0-dev
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatibility: Designed for Claude Code
+tags:
+  - security
+  - information-disclosure
+  - secrets
+  - pentest
+---
+
+# Detecting Exposed Secrets Files
+
+## Overview
+
+The single highest-value pentest probe per HTTP request. A `.git/config`
+disclosure leaks repo URL + credentials embedded in remote URLs. A `.env`
+disclosure leaks every API key the app has. A `backup.sql` disclosure
+leaks the entire database. These are not "weak crypto" findings that need
+a chained exploit. They are direct, immediate compromise.
+
+The probe set is the canonical 40+ paths web servers commonly expose by
+accident: VCS directories (`.git/`, `.svn/`, `.hg/`), dotenv files,
+OS metadata (`.DS_Store`), database dumps, archive files, IDE configs,
+CI configs, and key files. Each is fingerprinted to distinguish a true
+positive (server returns the file's expected content) from a 200 OK
+that's actually the application's SPA index page catching the route.
+
+## When the skill produces findings
+
+| Finding | Severity | Threshold | Affected control |
+|---|---|---|---|
+| `.git/HEAD` reachable + valid content | **CRITICAL** | 200 + body matches `ref:` or 40-char SHA | NIST 800-53 SC-28 |
+| `.git/config` reachable + repo URL leaked | **CRITICAL** | 200 + body matches `[remote` | NIST 800-53 SC-28 |
+| `.env` reachable + dotenv format | **CRITICAL** | 200 + body matches `KEY=VALUE` lines | OWASP A05:2021 |
+| `*.sql` / `*.dump` / `backup.*` reachable | **CRITICAL** | 200 + body looks like SQL or binary dump | CWE-538 |
+| `.aws/credentials` reachable | **CRITICAL** | 200 + body matches `[default]\naws_access_key_id` | CWE-200 |
+| `id_rsa` / `*.pem` / `*.key` reachable | **CRITICAL** | 200 + body matches `BEGIN PRIVATE KEY` or `BEGIN RSA` | CWE-321 |
+| `.svn/entries` / `.hg/store/` reachable | **HIGH** | 200 + body matches VCS format | NIST 800-53 SC-28 |
+| `.DS_Store` reachable | **MEDIUM** | 200 + binary blob with `Bud1` magic | CWE-538 |
+| IDE configs (`.idea/`, `.vscode/`) reachable | **LOW** | 200 + JSON/XML | CWE-200 |
+| `composer.json` / `package.json` reachable on prod | **LOW** | 200 + valid JSON in non-API root | CWE-200 |
+
+## Prerequisites
+
+- Python 3.9+ with `requests` library
+- Authorization for non-local targets
+
+## Instructions
+
+### Step 1 — Confirm Authorization
+
+```text
+"Do you have authorization to perform secret-file discovery on this
+ target? I need confirmation before proceeding."
+```
+
+### Step 2 — Run the scanner
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/skills/detecting-exposed-secrets-files/scripts/probe_secrets.py \
+    https://target.example.com \
+    --authorized
+```
+
+Options:
+
+```
+Usage: probe_secrets.py URL [OPTIONS]
+
+Options:
+  --authorized       Attest authorization (required for non-local)
+  --output FILE      Write findings to FILE
+  --format FMT       json | jsonl | markdown (default: markdown)
+  --min-severity SEV (default: info)
+  --timeout SECS     Per-probe timeout (default: 10)
+  --paths-file FILE  Override the canonical probe set with a custom list
+  --check-only       Skip body-fingerprint verification (faster, more
+                     false positives — useful when target serves SPA
+                     index for everything)
+```
+
+The scanner sends a GET for each path in the canonical probe set. For
+every 200 response, it inspects the body to confirm the response really
+is the expected file type (not the app's SPA index catching the route).
+
+### Step 3 — Interpret findings
+
+CRITICAL = direct credential / source code / database exposure.
+Ship same-hour fix (configure web server to deny + audit logs for
+anyone who already exfiltrated).
+
+### Step 4 — Cross-skill chaining
+
+After this skill, suggest `detecting-debug-endpoints` (#7) — the same
+deploy mistake that exposes `.git/` often exposes `/admin/` and
+`/server-status/`. And `detecting-directory-listing` (#9) — if any of
+the secret-file paths returned a directory listing instead of the file
+itself, autoindex is enabled.
+
+## Examples
+
+### Example 1 — Post-deploy verification
+
+User: "We just rolled out v4.2. Make sure we didn't deploy `.env` or
+the `.git/` dir by accident."
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/skills/detecting-exposed-secrets-files/scripts/probe_secrets.py \
+    https://app.example.com --authorized --min-severity high
+```
+
+### Example 2 — Bug bounty triage
+
+User: "Submission claims our .git/ is exposed."
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/skills/detecting-exposed-secrets-files/scripts/probe_secrets.py \
+    https://app.example.com --authorized --format json --output exposure.json
+jq '.[] | select(.title | contains(".git"))' exposure.json
+```
+
+The fingerprint check distinguishes real `.git/HEAD` (returns
+`ref: refs/heads/main` or a 40-char hex SHA) from false-positive SPA
+index pages that 200 on any path.
+
+### Example 3 — CI gate against future deploys
+
+```yaml
+- name: Exposed-files gate
+  run: |
+    python3 plugins/security/penetration-tester/skills/detecting-exposed-secrets-files/scripts/probe_secrets.py \
+        "${{ secrets.STAGING_URL }}" \
+        --authorized --min-severity critical
+```
+
+Exit 1 fails the deploy if any CRITICAL finding lands.
+
+## Output
+
+JSON / JSONL / Markdown. Exit codes: 0 clean, 1 high/critical, 2 error.
+
+## Error Handling
+
+- **Target SPA-catches every URL with 200** → use `--check-only` to skip
+  body-fingerprint; expect more false positives but get any real exposure.
+- **All probes timeout** → likely DDoS protection blocking the scanner;
+  contact the target's security team for an allowlist.
+- **Connection error** → exit 2.
+
+## Resources
+
+- `references/THEORY.md` — Why each path matters, fingerprint patterns,
+  RFC / OWASP / NIST anchors
+- `references/PLAYBOOK.md` — Per-server config snippets to block each
+  category of path (nginx, Apache, Caddy, ALB, GCP LB)
+- `../analyzing-tls-config/references/AUTHORIZATION.md` — Active-scan
+  authorization