@murk-security/runner-linux-arm64 0.0.0-stage → 0.7.0

package/runners/skills/web/graphql-exposure/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: graphql-exposure
+description: Detect and assess an exposed/over-permissive GraphQL endpoint via introspection, without authentication.
+when-to-use: a /graphql, /api/graphql, /v1/graphql or /query endpoint exists, or a response mentions GraphQL / __schema / Apollo.
+surface: web
+severity: high
+---
+
+# GraphQL exposure (unauthenticated)
+
+A read-only playbook for the `http` op. Goal: show that a GraphQL endpoint leaks
+its schema and/or returns data without authentication.
+
+## 1. Locate the endpoint
+Fetch common locations anonymously:
+`http {"path":"/graphql"}`, then `/api/graphql`, `/v1/graphql`, `/query`, `/graphiql`, `/playground`.
+A 200/400 with a JSON body mentioning `errors`/`data`/`__typename` is GraphQL.
+
+## 2. Introspection
+Run an introspection query over GET (read-only):
+`http {"path":"/graphql?query={__schema{types{name fields{name}}}}"}`.
+If the response contains `__schema` with type/field names, introspection is ENABLED
+— report it: it hands an attacker the full data model (types, fields, mutations).
+
+## 3. Harvest sensitive fields
+From the schema, note fields that should never be anonymously reachable:
+`password`, `passwordHash`, `ssn`, `token`, `secret`, `email`, `role`, `isAdmin`,
+and any `Query`/`Mutation` that reads or changes data without an auth argument.
+
+## 4. Prove data exposure
+Issue a narrow query for a sensitive field anonymously, e.g.
+`http {"path":"/graphql?query={users{id email ssn}}"}`.
+A 200 returning real values is a confirmed unauthenticated data exposure — cite the
+exact request + the proving response.
+
+## Evidence & severity
+- Introspection enabled alone: medium (information disclosure).
+- Introspection + any anonymous sensitive query returning data: high/critical.
+Report with the endpoint path, the query, and the response fields returned. Do NOT
+send mutations (this is a read-only assessment).

package/runners/skills.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Skill library for the Blackglass basic-harness product env (Phase 3).
+
+Progressive-disclosure skills, in the shape codex + grok-build converged on, but
+adapted to our action model. A skill is:
+
+    runners/skills/<category>/<name>/SKILL.md
+
+with simple `key: value` frontmatter (name, description, when-to-use, surface,
+severity) and a markdown PLAYBOOK body. Unlike codex/grok (which run in a shell
+and can bundle executable scripts), our prober's ONLY action surface is the env
+tool, so a skill carries no executable bundle -- it is pure methodology that tells
+the prober which http/recon ops to call, with which paths and payloads.
+
+Three disclosure levels, same as the references:
+  1. always-on INDEX  (name + when-to-use), budget-capped, injected into the brief
+  2. full BODY on demand via the get_skill env op
+  3. (n/a for us -- no bundled scripts; the body names the ops to call directly)
+
+prod_env.py imports this and exposes list_skills / get_skill ops; build_brief
+injects render_index() as part of the coverage floor.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+SKILLS_DIR = Path(os.environ.get("BASIC_HARNESS_SKILLS_DIR", Path(__file__).resolve().parent / "skills"))
+SKILL_FILE = "SKILL.md"
+INDEX_BUDGET = 6000          # max chars for the brief index (budget-cap like codex/grok)
+MAX_DESC_IN_INDEX = 200      # per-line description/when-to-use cap in the index
+MAX_NAME_LEN = 64
+
+_CACHE: list[dict] | None = None
+
+
+def _parse_frontmatter(text: str) -> tuple[dict, str]:
+    """Split a SKILL.md into (frontmatter dict, body). Minimal and dependency-free;
+    our frontmatter is controlled and uses flat `key: value` lines only."""
+    meta: dict = {}
+    body = text
+    if text.startswith("---"):
+        end = text.find("\n---", 3)
+        if end != -1:
+            fm = text[3:end]
+            body = text[end + 4:].lstrip("\n")
+            for line in fm.splitlines():
+                line = line.strip()
+                if not line or line.startswith("#") or ":" not in line:
+                    continue
+                k, _, v = line.partition(":")
+                meta[k.strip().lower()] = v.strip().strip('"').strip("'")
+    return meta, body
+
+
+def _normalize_name(name: str) -> str:
+    name = "".join(c if (c.isalnum() or c in "-_") else "-" for c in name.lower())
+    return name.strip("-")[:MAX_NAME_LEN]
+
+
+def _scan() -> list[dict]:
+    global _CACHE
+    if _CACHE is not None:
+        return _CACHE
+    skills: list[dict] = []
+    seen: set[str] = set()
+    if SKILLS_DIR.is_dir():
+        for md in sorted(SKILLS_DIR.rglob(SKILL_FILE)):
+            try:
+                text = md.read_text(encoding="utf-8")
+            except OSError:
+                continue
+            meta, body = _parse_frontmatter(text)
+            name = _normalize_name(meta.get("name") or md.parent.name)
+            if not name or name in seen:
+                continue
+            desc = meta.get("description", "").strip()
+            if not desc:
+                continue  # description is required (matches codex)
+            seen.add(name)
+            skills.append({
+                "name": name,
+                "description": desc,
+                "when_to_use": (meta.get("when-to-use") or meta.get("when_to_use") or "").strip(),
+                "surface": (meta.get("surface") or "").strip(),
+                "severity": (meta.get("severity") or "").strip(),
+                # The action tier a skill needs to be surfaced. A skill with no
+                # declared tier is passive discovery methodology (back-compat: the
+                # existing skills). An offensive playbook declares a higher tier so
+                # it is never surfaced to a lower-tier (e.g. production passive) run;
+                # the caller supplies the `allow` predicate that enforces this.
+                "tier": (meta.get("tier") or "").strip(),
+                "body": body.strip(),
+                "category": md.parent.parent.name if md.parent.parent != SKILLS_DIR else "",
+            })
+    _CACHE = skills
+    return skills
+
+
+def _visible(s: dict, allow) -> bool:
+    """Whether skill `s` may be surfaced on this run. `allow` is a predicate the
+    caller supplies, `allow(skill_tier) -> bool`, which decides from the run's own
+    action tier (the env owns the tier vocabulary, not this module). `allow` None
+    means no filtering (tests / tier-agnostic callers)."""
+    return True if allow is None else bool(allow(s.get("tier", "")))
+
+
+def _visible_skills(allow) -> list[dict]:
+    return [s for s in _scan() if _visible(s, allow)]
+
+
+def available(allow=None) -> bool:
+    return bool(_visible_skills(allow))
+
+
+def render_index(allow=None) -> str:
+    """Budget-capped index for the brief: one line per skill, name + when-to-use
+    (or description). Names are always kept; the trigger text is truncated and the
+    tail is dropped with an overflow note if the budget is exceeded. Only skills
+    the run's tier permits (per `allow`) appear, so an offensive playbook never
+    leaks into a lower-tier run's brief."""
+    skills = _visible_skills(allow)
+    if not skills:
+        return ""
+    lines, used = [], 0
+    for s in skills:
+        trigger = s["when_to_use"] or s["description"]
+        if len(trigger) > MAX_DESC_IN_INDEX:
+            trigger = trigger[:MAX_DESC_IN_INDEX - 1].rstrip() + "…"
+        line = f"- {s['name']}: {trigger}"
+        if used + len(line) + 1 > INDEX_BUDGET:
+            lines.append(f"- … and {len(skills) - len(lines)} more (call list_skills)")
+            break
+        lines.append(line)
+        used += len(line) + 1
+    return "\n".join(lines)
+
+
+def list_skills(allow=None) -> dict:
+    return {"ok": True, "skills": [
+        {k: s[k] for k in ("name", "description", "when_to_use", "surface", "severity", "category")}
+        for s in _visible_skills(allow)]}
+
+
+def get_skill(name: str, allow=None) -> dict:
+    want = _normalize_name(str(name))
+    for s in _scan():
+        if s["name"] == want:
+            if not _visible(s, allow):
+                # Defense in depth: a skill the run's tier does not permit cannot be
+                # loaded even by naming it directly (mirrors the env refusing a
+                # higher-tier op). Don't return the body or methodology.
+                return {"ok": False, "error": f"skill {s['name']!r} is not available at this action tier"}
+            return {"ok": True, "name": s["name"], "surface": s["surface"],
+                    "severity": s["severity"], "body": s["body"]}
+    names = ", ".join(s["name"] for s in _visible_skills(allow)) or "(none)"
+    return {"ok": False, "error": f"no skill {name!r}; available: {names}"}
+
+
+def handle(op: str, args: dict, allow=None):
+    """Return a result dict for a skill op, or None if op is not a skill op."""
+    if op == "list_skills":
+        return list_skills(allow)
+    if op == "get_skill":
+        return get_skill(args.get("name", ""), allow)
+    return None
+
+
+def describe_ops() -> dict:
+    return {
+        "list_skills": "{} list the deep playbooks you can load (name + when-to-use).",
+        "get_skill": '{"name": "..."} load a playbook\'s full methodology (which ops/paths/payloads to use).',
+    }