arkaos 4.16.0 → 4.17.0

package/core/governance/harness_scanner_cli.py

@@ -0,0 +1,131 @@
+"""`npx arkaos shield` — the operator-facing surface of the harness scanner.
+
+Two roots matter and both are scanned by default: the user config
+(``~/.claude``) and the project the operator is standing in. Splitting
+them would be a footgun — the MCP servers that run with the agent's
+permissions usually live in the project's ``.mcp.json``, while the
+permissions themselves live in the user settings. A tool that reports a
+clean bill of health because it only looked at one of them is worse than
+no tool.
+
+Exit codes: 0 = grade A/B, 1 = grade C/D, 2 = grade F or a CRITICAL
+finding. CI can gate on it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from core.governance.harness_scanner import (
+    PENALTY,
+    Finding,
+    ScanReport,
+    Severity,
+    scan,
+)
+
+_ICON = {
+    Severity.CRITICAL: "✗",
+    Severity.HIGH: "✗",
+    Severity.MEDIUM: "⚠",
+    Severity.LOW: "·",
+}
+
+
+def merge(reports: list[ScanReport]) -> ScanReport:
+    """One grade for the operator, not one per file they must add up."""
+    merged = ScanReport(root=reports[0].root if reports else Path("."))
+    for report in reports:
+        merged.files_scanned += report.files_scanned
+        for finding in report.findings:
+            merged.findings.append(_qualify(finding, report.root))
+    merged.findings.sort(key=lambda f: (-PENALTY[f.severity], f.rule))
+    return merged
+
+
+def _qualify(finding: Finding, root: Path) -> Finding:
+    """Name the root in `where` so two scans cannot be confused."""
+    return Finding(
+        rule=finding.rule,
+        severity=finding.severity,
+        where=f"{root}/{finding.where}",
+        detail=finding.detail,
+        fix=finding.fix,
+    )
+
+
+def _plural(count: int, noun: str) -> str:
+    return f"{count} {noun}" if count == 1 else f"{count} {noun}s"
+
+
+def render(report: ScanReport) -> str:
+    scanned = _plural(report.files_scanned, "config file")
+    lines = ["", f"  ArkaOS Shield — {scanned} scanned", ""]
+    if not report.findings:
+        lines += [f"  Grade {report.grade} ({report.score}/100) — nothing "
+                  f"to report.", ""]
+        return "\n".join(lines)
+    for severity in Severity:
+        found = report.by_severity(severity)
+        if not found:
+            continue
+        lines.append(f"  {severity.value.upper()}")
+        for finding in found:
+            lines.append(f"    {_ICON[severity]} {finding.rule}  "
+                         f"({finding.where})")
+            lines.append(f"      {finding.detail}")
+            lines.append(f"      fix: {finding.fix}")
+        lines.append("")
+    summary = _plural(len(report.findings), "finding")
+    lines += [f"  Grade {report.grade} ({report.score}/100) — {summary}.", ""]
+    return "\n".join(lines)
+
+
+def exit_code(report: ScanReport) -> int:
+    # grade already collapses to F on any CRITICAL, so the letter is the
+    # single source of the exit contract.
+    if report.grade == "F":
+        return 2
+    return 1 if report.grade in ("C", "D") else 0
+
+
+def _roots(args: argparse.Namespace) -> list[Path]:
+    if args.path:
+        return [Path(p).expanduser() for p in args.path]
+    return [Path.home() / ".claude", Path.cwd()]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="arkaos shield",
+        description=(
+            "Scan the agent harness configuration for vulnerabilities: "
+            "over-permissive allow rules, secrets in config, hook command "
+            "injection, unpinned MCP servers, prompt injection in "
+            "instruction files."
+        ),
+        epilog="Exit: 0 = A/B, 1 = C/D, 2 = F or any CRITICAL finding.",
+    )
+    parser.add_argument(
+        "path", nargs="*",
+        help="Config roots to scan. Default: ~/.claude and the cwd.",
+    )
+    parser.add_argument(
+        "--json", action="store_true", dest="as_json",
+        help="Machine-readable output.",
+    )
+    args = parser.parse_args(argv)
+
+    report = merge([scan(root) for root in _roots(args) if root.is_dir()])
+    if args.as_json:
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        print(render(report))
+    return exit_code(report)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/core/skills/__init__.py

@@ -0,0 +1,21 @@
+"""Skill-layer models and validators (provenance, schema)."""
+
+from core.skills.provenance import (
+    FIRST_PARTY,
+    METADATA_FIELDS,
+    ProvenanceError,
+    SkillProvenance,
+    declares_provenance,
+    parse_provenance,
+    provenance_issues,
+)
+
+__all__ = [
+    "FIRST_PARTY",
+    "METADATA_FIELDS",
+    "ProvenanceError",
+    "SkillProvenance",
+    "declares_provenance",
+    "parse_provenance",
+    "provenance_issues",
+]

package/core/skills/provenance.py

@@ -0,0 +1,195 @@
+"""Skill provenance — supply-chain lineage for every SKILL.md.
+
+A skill either originates in ArkaOS or it is derived from someone
+else's work. Third-party lineage is a security property, not trivia: a
+skill tree with no origin field cannot be audited after the fact, and
+"which licence is this under?" becomes unanswerable the moment the
+author who ported it moves on.
+
+Contract (opt-in, absence means first-party):
+
+    ---
+    name: dev/silent-failure-hunter
+    description: ...
+    allowed-tools: [Read, Grep, Glob]
+    metadata:
+      origin: ecc-derived
+      source: https://github.com/affaan-m/ecc
+      license: MIT
+    ---
+
+``origin`` is a lowercase slug (``^[a-z][a-z0-9-]*$``). ``arkaos`` — or
+no metadata block at all — is first-party and needs nothing else. ANY
+other origin MUST declare ``source`` (an http(s) URL) and ``license``.
+
+**Fail closed.** A block that is present but unusable — unparseable
+YAML, a tab-indented body, ``metadata`` bound to a scalar, a misspelt
+key (``metadatas:``, ``orgin:``) — is an ERROR, never a silent fall
+back to first-party. Laundering a derived skill into ``arkaos`` by
+typo is the one failure this module exists to prevent.
+
+No parser can see the last vector: a port that simply never writes the
+block reads as first-party, and a typo net will always have a hole
+(``metdata:``, ``provenance:``, ``metadata: {}``). Omission is closed
+somewhere else — ``config/skills-provenance.yaml`` classifies every
+skill in the tree as baseline, derived, or self-declaring, and
+``tests/python/test_skill_provenance.py`` fails CI on any skill that is
+none of the three. A new skill must therefore say what it is. This
+module cannot enforce that and does not claim to.
+
+Consumed by ``scripts/skill_validator.py`` (per-skill score) and
+``scripts/marketplace_gen.py`` (``knowledge/skills-manifest.json``,
+which carries the full origin/source/licence triple, not just origin).
+"""
+
+from __future__ import annotations
+
+import re
+
+import yaml
+from pydantic import BaseModel, Field, ValidationError, model_validator
+
+FIRST_PARTY = "arkaos"
+METADATA_FIELDS = ("origin", "source", "license")
+
+_FRONTMATTER = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
+_ORIGIN_SLUG = re.compile(r"^[a-z][a-z0-9-]*$")
+# https only: a licence trail that can be MITM'd is not a trail.
+_URL = re.compile(r"^https://\S+$")
+# Near-misses for `metadata` — a typo must not read as "no block".
+_METADATA_TYPO = re.compile(r"^meta[-_ ]?datas?$", re.IGNORECASE)
+
+
+class ProvenanceError(ValueError):
+    """The provenance block is present but cannot be trusted."""
+
+
+class SkillProvenance(BaseModel):
+    """Where a skill came from, and under what licence."""
+
+    origin: str = Field(default=FIRST_PARTY)
+    source: str | None = None
+    license: str | None = None
+
+    @model_validator(mode="after")
+    def _derived_needs_a_trail(self) -> SkillProvenance:
+        if not _ORIGIN_SLUG.match(self.origin):
+            raise ValueError(
+                f"origin {self.origin!r} is not a lowercase slug "
+                f"(^[a-z][a-z0-9-]*$)"
+            )
+        if self.origin == FIRST_PARTY:
+            return self._first_party_carries_no_trail()
+        missing = [f for f in ("source", "license") if not getattr(self, f)]
+        if missing:
+            raise ValueError(
+                f"origin {self.origin!r} is third-party — "
+                f"{', '.join(missing)} required"
+            )
+        if not _URL.match(self.source or ""):
+            raise ValueError(f"source {self.source!r} is not an https URL")
+        return self
+
+    def _first_party_carries_no_trail(self) -> SkillProvenance:
+        """`arkaos` plus a source/licence is an unresolved contradiction.
+
+        Either the skill is ours and there is nothing to attribute, or
+        it is not and the origin is wrong. Silence would let a bad port
+        keep its upstream URL while claiming to be first-party.
+        """
+        declared = [f for f in ("source", "license") if getattr(self, f)]
+        if declared:
+            raise ValueError(
+                f"origin {FIRST_PARTY!r} is first-party but declares "
+                f"{', '.join(declared)} — set a third-party origin or "
+                f"drop the field"
+            )
+        return self
+
+    @property
+    def is_first_party(self) -> bool:
+        return self.origin == FIRST_PARTY
+
+
+def _frontmatter(content: str) -> dict:
+    """The YAML frontmatter mapping. Raises when present but broken."""
+    match = _FRONTMATTER.match(content)
+    if not match:
+        return {}
+    try:
+        data = yaml.safe_load(match.group(1))
+    except yaml.YAMLError as exc:
+        detail = str(exc).replace("\n", " ")[:120]
+        raise ProvenanceError(
+            f"frontmatter YAML does not parse: {detail}"
+        ) from exc
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ProvenanceError("frontmatter is not a mapping")
+    return data
+
+
+def _metadata_block(frontmatter: dict) -> dict | None:
+    """The `metadata` mapping, or None when genuinely absent."""
+    if "metadata" in frontmatter:
+        block = frontmatter["metadata"]
+        if not isinstance(block, dict):
+            raise ProvenanceError(
+                "metadata must be a mapping of origin/source/license"
+            )
+        return block
+    typos = [
+        key for key in frontmatter
+        if isinstance(key, str) and _METADATA_TYPO.match(key)
+    ]
+    if typos:
+        raise ProvenanceError(
+            f"key {typos[0]!r} is not read — did you mean 'metadata'?"
+        )
+    return None
+
+
+def parse_provenance(content: str) -> SkillProvenance:
+    """Read a SKILL.md body. Absent metadata means first-party.
+
+    Raises ``ProvenanceError``/``ValidationError`` when the block is
+    present but incoherent — callers that must not raise use
+    ``provenance_issues`` instead.
+    """
+    block = _metadata_block(_frontmatter(content))
+    if block is None:
+        return SkillProvenance()
+    unknown = sorted(str(k) for k in block if k not in METADATA_FIELDS)
+    if unknown:
+        raise ProvenanceError(
+            f"unknown metadata keys: {', '.join(unknown)} "
+            f"(expected {', '.join(METADATA_FIELDS)})"
+        )
+    return SkillProvenance(**block)
+
+
+def declares_provenance(content: str) -> bool:
+    """Did the author WRITE a block, or is this the default?
+
+    ``parse_provenance`` collapses "declared arkaos" and "said nothing"
+    into the same value — correct for reading, useless for the one
+    question the classification control has to answer.
+    """
+    try:
+        return _metadata_block(_frontmatter(content)) is not None
+    except ProvenanceError:
+        return True  # broken but attempted; provenance_issues owns it
+
+
+def provenance_issues(content: str) -> list[str]:
+    """Non-raising validation. Empty list means the skill is clean."""
+    try:
+        parse_provenance(content)
+    except ProvenanceError as exc:
+        return [str(exc)]
+    except ValidationError as exc:
+        return [
+            err["msg"].removeprefix("Value error, ") for err in exc.errors()
+        ]
+    return []

package/installer/cli.js

@@ -68,6 +68,7 @@ Usage:
   npx arkaos models set <role> <provider>/<model>  Re-route a role
   npx arkaos mcp start        Start the arka-tools MCP server (stdio; --write enables writes)
   npx arkaos update --skills <curated|full>  Choose the deployed skill set (default: curated on fresh installs)
+  npx arkaos shield           Scan the harness config for vulnerabilities (--json)
   npx arkaos doctor           Run health checks
   npx arkaos uninstall        Remove ArkaOS
 
@@ -90,6 +91,8 @@ Examples:
   npx arkaos index                     Index knowledge base (Obsidian vault)
   npx arkaos search "query"            Search indexed knowledge
   npx arkaos doctor                     Verify installation health
+  npx arkaos shield                     Scan the harness config (exit 2 = critical)
+  npx arkaos shield --json              Machine-readable, for CI
 `);
   process.exit(0);
 }
@@ -208,6 +211,27 @@ async function main() {
       break;
     }
 
+    case "shield": {
+      // The harness config as attack surface. Exit code is the contract
+      // CI gates on (0 = A/B, 1 = C/D, 2 = F or any CRITICAL), so the
+      // child's code is propagated verbatim rather than collapsed to 1.
+      const { spawnSync } = await import("node:child_process");
+      const repoRootShield = join(__dirname, "..");
+      const pyShield = getArkaosPython();
+      if (!pyShield) { console.error("No Python found. Run: npx arkaos install"); process.exit(1); }
+      const shieldArgs = process.argv.slice(3);
+      const shieldRun = spawnSync(
+        pyShield,
+        ["-m", "core.governance.harness_scanner_cli", ...shieldArgs],
+        {
+          stdio: "inherit",
+          cwd: process.cwd(),
+          env: { ...process.env, ARKAOS_ROOT: repoRootShield, PYTHONPATH: repoRootShield },
+        }
+      );
+      process.exit(shieldRun.status === null ? 1 : shieldRun.status);
+    }
+
     case "index": {
       const { execFileSync } = await import("node:child_process");
       const repoRoot = join(__dirname, "..");

package/installer/doctor.js

@@ -531,5 +531,51 @@ export async function doctor(options = {}) {
   }
 
   console.log(`\n  Results: ${passed} passed, ${warned} warnings, ${failed} failures\n`);
+  await securityAdvisory();
   if (failed > 0) process.exit(1);
 }
+
+// Doctor answers "is the install healthy?". It never answered "is the
+// install SAFE?" — a config can be perfectly healthy and still hand a
+// third party the right to run code on this machine. The scanner does
+// that, and doctor is where the operator already looks.
+//
+// Advisory only: it prints the grade and never changes doctor's exit
+// code. A health check that starts failing on a pre-existing security
+// posture would be a breaking change to everyone's CI, and the way to
+// get a security tool ignored is to make it block on day one.
+async function securityAdvisory() {
+  const python = getArkaosPython();
+  const repoRoot = getRepoRoot();
+  if (!python || !repoRoot) return;
+  const { spawnSync } = await import("node:child_process");
+  const run = spawnSync(
+    python,
+    ["-m", "core.governance.harness_scanner_cli", "--json"],
+    {
+      encoding: "utf-8",
+      cwd: process.cwd(),
+      env: { ...process.env, ARKAOS_ROOT: repoRoot, PYTHONPATH: repoRoot },
+    }
+  );
+  // A crash must not read as "clean". If the scanner did not return a
+  // parseable report, say so — the same crash-is-not-clean rule the
+  // scanner enforces internally.
+  let report = null;
+  if (run.status !== null && run.stdout) {
+    try { report = JSON.parse(run.stdout); } catch { report = null; }
+  }
+  if (!report || !Array.isArray(report.findings)) {
+    console.log("  Security: scan did not complete — run `npx arkaos shield` directly\n");
+    return;
+  }
+
+  const cross = process.stdout.isTTY ? "\x1b[31m✗\x1b[0m" : "x";
+  const n = report.findings.length;
+  const plural = n === 1 ? "finding" : "findings";
+  console.log(`  Security: grade ${report.grade} (${report.score}/100), ${n} ${plural}`);
+  for (const finding of report.findings.filter((f) => f.severity === "critical").slice(0, 3)) {
+    console.log(`     ${cross} ${finding.rule} — ${finding.where}`);
+  }
+  console.log(n > 0 ? "     Run: npx arkaos shield\n" : "");
+}