farai 0.1.2 → 0.1.4

package/docker/kali/farai-tool-manifest.json

@@ -33,6 +33,7 @@
     "hashcat",
     "hydra",
     "impacket-scripts",
+    "imagemagick",
     "iproute2",
     "iptables",
     "iputils-ping",
@@ -56,6 +57,7 @@
     "nuclei",
     "openssh-client",
     "openssl",
+    "poppler-utils",
     "pipx",
     "procps",
     "python3",
@@ -75,6 +77,7 @@
     "steghide",
     "subfinder",
     "tcpdump",
+    "tesseract-ocr",
     "testssl.sh",
     "theharvester",
     "tree",
@@ -98,14 +101,17 @@
       "curl",
       "dig",
       "file",
+      "identify",
       "ip",
       "iptables",
       "jq",
       "nc",
       "openssl",
+      "pdftotext",
       "ping",
       "rg",
       "ssh",
+      "tesseract",
       "unzip",
       "wget",
       "whois",

package/docker/kali/farai_mitmproxy_mcp.py

@@ -5,8 +5,10 @@ from __future__ import annotations
 import base64
 import json
 import os
+import re
 import sqlite3
 import sys
+import uuid
 from datetime import datetime, timezone
 from typing import Any
 
@@ -28,15 +30,16 @@ def env_int(name: str, default: int, minimum: int, maximum: int) -> int:
 MAX_BODY_PREVIEW = env_int("FARAI_PROXY_BODY_PREVIEW_BYTES", 65536, 1024, 1024 * 1024)
 MAX_MESSAGE_PREVIEW = env_int("FARAI_PROXY_MESSAGE_PREVIEW_BYTES", 16384, 1024, 256 * 1024)
 MAX_MESSAGES = env_int("FARAI_PROXY_MAX_MESSAGES", 200, 1, 1000)
+REPLAY_CORRELATION_HEADER = "X-Farai-Replay-Correlation"
 
 
-class FlowStoreV2:
+class FlowStore:
     def __init__(self, db_path: str):
         self.db_path = db_path
         with self._connect() as conn:
             conn.execute(
                 """
-                CREATE TABLE IF NOT EXISTS farai_flows_v2 (
+                CREATE TABLE IF NOT EXISTS farai_flows (
                     id TEXT PRIMARY KEY,
                     kind TEXT NOT NULL,
                     timestamp REAL NOT NULL,
@@ -46,12 +49,12 @@ class FlowStoreV2:
                 """
             )
             conn.execute(
-                "CREATE INDEX IF NOT EXISTS idx_farai_flows_v2_timestamp "
-                "ON farai_flows_v2(timestamp)"
+                "CREATE INDEX IF NOT EXISTS idx_farai_flows_timestamp "
+                "ON farai_flows(timestamp)"
             )
             conn.execute(
-                "CREATE INDEX IF NOT EXISTS idx_farai_flows_v2_kind "
-                "ON farai_flows_v2(kind)"
+                "CREATE INDEX IF NOT EXISTS idx_farai_flows_kind "
+                "ON farai_flows(kind)"
             )
 
     def _connect(self) -> sqlite3.Connection:
@@ -65,7 +68,7 @@ class FlowStoreV2:
         with self._connect() as conn:
             conn.execute(
                 """
-                INSERT INTO farai_flows_v2(id, kind, timestamp, summary_json, detail_json)
+                INSERT INTO farai_flows(id, kind, timestamp, summary_json, detail_json)
                 VALUES (?, ?, ?, ?, ?)
                 ON CONFLICT(id) DO UPDATE SET
                     kind=excluded.kind,
@@ -78,7 +81,7 @@ class FlowStoreV2:
 
     def summaries(self, limit: int, kind: str | None = None) -> list[dict[str, Any]]:
         bounded_limit = max(1, min(int(limit), 1000))
-        sql = "SELECT summary_json FROM farai_flows_v2"
+        sql = "SELECT summary_json FROM farai_flows"
         params: list[Any] = []
         if kind:
             sql += " WHERE kind = ?"
@@ -92,22 +95,42 @@ class FlowStoreV2:
     def detail(self, flow_id: str) -> dict[str, Any] | None:
         with self._connect() as conn:
             row = conn.execute(
-                "SELECT detail_json FROM farai_flows_v2 WHERE id = ?", (flow_id,)
+                "SELECT detail_json FROM farai_flows WHERE id = ?", (flow_id,)
             ).fetchone()
         return json.loads(row[0]) if row else None
 
     def clear(self) -> None:
         with self._connect() as conn:
-            conn.execute("DELETE FROM farai_flows_v2")
+            conn.execute("DELETE FROM farai_flows")
 
 
 class FaraiTrafficRecorder(UPSTREAM_TRAFFIC_RECORDER):
     def __init__(self, scope: Any):
         super().__init__(scope)
-        self.v2 = FlowStoreV2(self.db.db_path)
+        self.flows = FlowStore(self.db.db_path)
+        self.intercept_config: dict[str, Any] = {
+            "enabled": False,
+            "host_pattern": ".*",
+            "path_pattern": ".*",
+            "methods": [],
+        }
+        self.pending_intercepts: dict[str, http.HTTPFlow] = {}
+        self.replay_correlations: dict[str, dict[str, str]] = {}
 
     def request(self, flow: http.HTTPFlow) -> None:
+        correlation = flow.request.headers.get(REPLAY_CORRELATION_HEADER)
+        if correlation:
+            flow.request.headers.pop(REPLAY_CORRELATION_HEADER, None)
+            replay = self.replay_correlations.get(str(correlation))
+            if replay is not None:
+                replay["descendantFlowId"] = flow.id
+                metadata = getattr(flow, "metadata", None)
+                if isinstance(metadata, dict):
+                    metadata["faraiReplayParentId"] = replay["parentFlowId"]
         super().request(flow)
+        if self._should_intercept(flow):
+            flow.intercept()
+            self.pending_intercepts[flow.id] = flow
         self._capture(flow)
 
     def response(self, flow: http.HTTPFlow) -> None:
@@ -160,24 +183,106 @@ class FaraiTrafficRecorder(UPSTREAM_TRAFFIC_RECORDER):
     def dns_error(self, flow: dns.DNSFlow) -> None:
         self._capture(flow)
 
-    def get_flow_summary_v2(self, limit: int = 20, kind: str | None = None) -> list[dict[str, Any]]:
-        return self.v2.summaries(limit, kind)
+    def farai_flow_summaries(self, limit: int = 20, kind: str | None = None) -> list[dict[str, Any]]:
+        return self.flows.summaries(limit, kind)
 
-    def get_flow_detail_v2(self, flow_id: str) -> dict[str, Any] | None:
-        return self.v2.detail(flow_id)
+    def farai_flow_detail(self, flow_id: str) -> dict[str, Any] | None:
+        return self.flows.detail(flow_id)
 
     def clear(self) -> None:
         super().clear()
-        self.v2.clear()
+        self.flows.clear()
+
+    def scope_state(self) -> dict[str, Any]:
+        return {"allowedDomains": list(self.scope.config.allowed_domains)}
+
+    def configure_intercept(
+        self,
+        enabled: bool,
+        host_pattern: str = ".*",
+        path_pattern: str = ".*",
+        methods: list[str] | None = None,
+    ) -> dict[str, Any]:
+        re.compile(host_pattern)
+        re.compile(path_pattern)
+        self.intercept_config = {
+            "enabled": bool(enabled),
+            "host_pattern": host_pattern,
+            "path_pattern": path_pattern,
+            "methods": sorted({method.upper() for method in (methods or [])}),
+        }
+        return {**self.intercept_config, "pending": len(self.pending_intercepts)}
+
+    def list_intercepts(self) -> list[dict[str, Any]]:
+        result: list[dict[str, Any]] = []
+        for flow in self.pending_intercepts.values():
+            summary, _, _ = serialize_http(flow)
+            result.append(summary)
+        return sorted(result, key=lambda item: str(item.get("timestamp", "")))
+
+    def begin_replay(self, parent_flow_id: str) -> tuple[str, dict[str, str]]:
+        token = uuid.uuid4().hex
+        state = {"parentFlowId": parent_flow_id}
+        self.replay_correlations[token] = state
+        return token, state
+
+    def finish_replay(self, token: str) -> dict[str, str]:
+        return self.replay_correlations.pop(token, {})
+
+    def resolve_intercept(
+        self,
+        flow_id: str,
+        action: str,
+        method: str | None = None,
+        url: str | None = None,
+        headers: dict[str, str] | None = None,
+        body: str | None = None,
+    ) -> dict[str, Any]:
+        flow = self.pending_intercepts.pop(flow_id, None)
+        if flow is None:
+            raise ValueError(f"Unknown pending intercepted flow: {flow_id}")
+        if action == "drop":
+            flow.kill()
+            return {"flowId": flow_id, "action": "drop"}
+        if action not in {"forward", "edit"}:
+            self.pending_intercepts[flow_id] = flow
+            raise ValueError("action must be forward, edit, or drop")
+        if action == "edit":
+            if method:
+                flow.request.method = method.upper()
+            if url:
+                flow.request.url = url
+            for key, value in (headers or {}).items():
+                flow.request.headers[key] = value
+            if body is not None:
+                flow.request.text = body
+        flow.resume()
+        return {"flowId": flow_id, "action": action}
+
+    def _should_intercept(self, flow: http.HTTPFlow) -> bool:
+        config = self.intercept_config
+        if not config["enabled"] or flow.id in self.pending_intercepts:
+            return False
+        methods = config["methods"]
+        return (
+            (not methods or flow.request.method.upper() in methods)
+            and re.search(config["host_pattern"], http_display_host(flow.request)) is not None
+            and re.search(config["path_pattern"], flow.request.path) is not None
+        )
 
     def _capture(self, flow: Any) -> None:
         try:
             if not self._is_allowed(flow):
                 return
             summary, detail, timestamp = serialize_flow(flow)
-            self.v2.save(summary, detail, timestamp)
+            metadata = getattr(flow, "metadata", None)
+            parent_flow_id = metadata.get("faraiReplayParentId") if isinstance(metadata, dict) else None
+            if parent_flow_id:
+                summary["parentFlowId"] = parent_flow_id
+                detail["parentFlowId"] = parent_flow_id
+            self.flows.save(summary, detail, timestamp)
         except Exception as exc:
-            print(f"Failed to save Farai v2 flow: {exc}", file=sys.stderr)
+            print(f"Failed to save Farai flow: {exc}", file=sys.stderr)
 
     def _is_allowed(self, flow: Any) -> bool:
         if isinstance(flow, http.HTTPFlow):
@@ -537,24 +642,150 @@ def optional(target: dict[str, Any], key: str, value: Any) -> None:
 
 
 @server.mcp.tool()
-async def get_flow_summary_v2(limit: int = 20, kind: str | None = None) -> str:
+async def proxy_flow_summaries(limit: int = 20, kind: str | None = None) -> str:
     """Return HTTP, WebSocket, TCP, UDP, and DNS flow summaries."""
     recorder = server.controller.recorder
     if not isinstance(recorder, FaraiTrafficRecorder):
         return "[]"
-    return json.dumps(recorder.get_flow_summary_v2(limit, kind), indent=2)
+    return json.dumps(recorder.farai_flow_summaries(limit, kind), indent=2)
 
 
 @server.mcp.tool()
-async def inspect_flow_v2(flow_id: str) -> str:
+async def proxy_flow_inspect(flow_id: str) -> str:
     """Return protocol-aware detail for a captured flow."""
     recorder = server.controller.recorder
     if not isinstance(recorder, FaraiTrafficRecorder):
         return "Couldn't find that flow."
-    detail = recorder.get_flow_detail_v2(flow_id)
+    detail = recorder.farai_flow_detail(flow_id)
     return json.dumps(detail, indent=2) if detail else "Couldn't find that flow."
 
 
+@server.mcp.tool()
+async def proxy_replay_correlated(
+    flow_id: str,
+    method: str | None = None,
+    headers_json: str | None = None,
+    body: str | None = None,
+    timeout: float = 30.0,
+) -> str:
+    """Replay an HTTP flow and return its exact captured descendant flow id."""
+    recorder = server.controller.recorder
+    if not isinstance(recorder, FaraiTrafficRecorder):
+        return json.dumps({"ok": False, "error": "Farai recorder is unavailable."})
+    if recorder.farai_flow_detail(flow_id) is None:
+        return json.dumps({"ok": False, "error": f"Couldn't find flow {flow_id}."})
+    try:
+        headers = json.loads(headers_json) if headers_json else {}
+    except json.JSONDecodeError as exc:
+        return json.dumps({"ok": False, "error": f"Invalid headers_json: {exc}"})
+    if not isinstance(headers, dict) or not all(isinstance(key, str) and isinstance(value, str) for key, value in headers.items()):
+        return json.dumps({"ok": False, "error": "headers_json must encode a string-to-string object."})
+
+    # Upstream treats None as "reuse the captured body"; an empty string omits it.
+    resolved_body = "" if body == "__omit__" else body
+    variables = getattr(server.controller, "session_variables", {})
+    resolver = getattr(server, "_resolve_template", None)
+    if variables and callable(resolver):
+        headers = json.loads(resolver(json.dumps(headers), variables))
+        if resolved_body:
+            resolved_body = resolver(resolved_body, variables)
+
+    token, correlation = recorder.begin_replay(flow_id)
+    headers[REPLAY_CORRELATION_HEADER] = token
+    try:
+        message = await server.controller.replay_request(flow_id, method, headers, resolved_body, timeout)
+        result = recorder.finish_replay(token)
+    except Exception as exc:
+        recorder.finish_replay(token)
+        return json.dumps({"ok": False, "parentFlowId": flow_id, "error": str(exc)})
+    ok = not any(marker in message.lower() for marker in ("couldn't find", "didn't work", "invalid"))
+    return json.dumps(
+        {
+            "ok": ok,
+            **correlation,
+            **result,
+            "message": message,
+            **({} if ok else {"error": message}),
+        },
+        indent=2,
+    )
+
+
+@server.mcp.tool()
+async def proxy_scope_get() -> str:
+    """Return Farai's active mitmproxy capture scope."""
+    recorder = server.controller.recorder
+    if not isinstance(recorder, FaraiTrafficRecorder):
+        return json.dumps({"allowedDomains": []})
+    return json.dumps(recorder.scope_state(), indent=2)
+
+
+@server.mcp.tool()
+async def proxy_intercept_configure(
+    enabled: bool,
+    host_pattern: str = ".*",
+    path_pattern: str = ".*",
+    methods: list[str] | None = None,
+) -> str:
+    """Enable or disable Farai's manual request interception queue."""
+    recorder = server.controller.recorder
+    if not isinstance(recorder, FaraiTrafficRecorder):
+        raise RuntimeError("Farai recorder is unavailable.")
+    try:
+        return json.dumps(
+            recorder.configure_intercept(enabled, host_pattern, path_pattern, methods),
+            indent=2,
+        )
+    except re.error as exc:
+        raise ValueError(f"Invalid interception pattern: {exc}") from exc
+
+
+@server.mcp.tool()
+async def proxy_intercept_get() -> str:
+    """Return Farai's manual interception configuration and queue size."""
+    recorder = server.controller.recorder
+    if not isinstance(recorder, FaraiTrafficRecorder):
+        return json.dumps({"enabled": False, "pending": 0})
+    return json.dumps(
+        {**recorder.intercept_config, "pending": len(recorder.pending_intercepts)},
+        indent=2,
+    )
+
+
+@server.mcp.tool()
+async def proxy_intercept_list() -> str:
+    """List requests currently paused in Farai's interception queue."""
+    recorder = server.controller.recorder
+    if not isinstance(recorder, FaraiTrafficRecorder):
+        return "[]"
+    return json.dumps(recorder.list_intercepts(), indent=2)
+
+
+@server.mcp.tool()
+async def proxy_intercept_resolve(
+    flow_id: str,
+    action: str,
+    method: str | None = None,
+    url: str | None = None,
+    headers_json: str | None = None,
+    body: str | None = None,
+) -> str:
+    """Forward, edit, or drop one request from Farai's interception queue."""
+    recorder = server.controller.recorder
+    if not isinstance(recorder, FaraiTrafficRecorder):
+        raise RuntimeError("Farai recorder is unavailable.")
+    headers = json.loads(headers_json) if headers_json else None
+    if headers is not None and (
+        not isinstance(headers, dict)
+        or not all(isinstance(key, str) and isinstance(value, str) for key, value in headers.items())
+    ):
+        raise ValueError("headers_json must encode a string-to-string object.")
+    return json.dumps(
+        recorder.resolve_intercept(flow_id, action, method, url, headers, body),
+        indent=2,
+    )
+
+
 server.TrafficRecorder = FaraiTrafficRecorder
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "farai",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "description": "Cyber-first freestyle local AI agent",
@@ -60,6 +60,7 @@
   },
   "dependencies": {
     "@opentui/core": "0.5.8",
+    "ajv": "8.20.0",
     "bun-pty": "0.4.10",
     "entities": "7.0.1",
     "fuzzysort": "3.1.0",

package/src/agent-skills/library/binary-exploitation/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: binary-exploitation
+description: "Workflow for pwn and memory-corruption challenges: interface discovery, mitigations, crash triage, primitive construction, local exploit validation, and remote adaptation. Use for buffer overflows, format strings, heap bugs, ROP, shellcode, race exploitation, or exploit development against a supplied binary/service."
+---
+
+# binary exploitation
+
+build and validate one exploitation primitive at a time.
+
+1. identify architecture, mitigations, linkage, libc/loader information, protocol or menu behavior, and how input reaches the process.
+2. reproduce a controlled failure locally. determine the exact offset and root cause before building a payload around it.
+3. name the primitive you have and the next primitive required: instruction-pointer control, leak, arbitrary read/write, allocation control, stack pivot, or code execution.
+4. construct the smallest payload that proves each transition. inspect registers, memory, stack alignment, bad bytes, and process state rather than inferring success from a disconnect.
+5. script the interaction early enough to make attempts deterministic, but keep payload stages observable while debugging.
+6. only after the local path is stable, account for remote differences such as libc, loader, ASLR, buffering, timing, file descriptors, and network framing.
+
+## recovery
+
+- inconsistent offset: verify the exact input path, newline handling, encoding, and crash context.
+- gadget or address failure: re-check architecture, module base, PIE, stack alignment, and bad bytes.
+- local success but remote failure: preserve the local proof, then isolate one environmental difference at a time.
+- no obvious memory bug: return to input boundaries and state transitions; do not force a ROP approach onto a logic or crypto challenge.
+
+## completion
+
+confirm the requested effect through process behavior or recovered output. a crash, probable gadget chain, or unexplained connection close is not proof of exploitation.

package/src/agent-skills/library/binary-reversing/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: binary-reversing
+description: Workflow for understanding native, managed, Go, Rust, JVM, Android, firmware, or obfuscated binaries and recovering hidden logic or data. Use for reverse-engineering challenges, crackmes, malware logic, decompilation, key/flag recovery, or when source is unavailable; pair with binary-exploitation only when memory corruption is the objective.
+---
+
+# binary reversing
+
+move from cheap structural facts to the smallest control-flow slice that answers the objective.
+
+1. identify format, architecture, linkage, symbols, protections, runtime, imports, sections, and obvious embedded artifacts. record facts before interpreting them.
+2. run the program with bounded, representative inputs when safe and useful. observe files, arguments, environment, stdout/stderr, and system interactions instead of guessing its interface from strings alone.
+3. locate the success, comparison, decryption, parsing, or output path. work backward through callers and data references; avoid decompiling the entire binary without a question.
+4. reconcile decompiler output with disassembly or runtime state whenever types, compiler optimizations, obfuscation, or stripped symbols make the pseudocode ambiguous.
+5. extract constants and encode the recovered transformation in a small script. validate it against known program behavior or by round-tripping an input.
+
+## runtime-aware guidance
+
+- Go/Rust/managed binaries often retain metadata that is more useful than generic string scraping; use runtime-aware symbols and metadata before treating the file as ordinary stripped native code.
+- packed or self-modifying code may require observing the unpacked memory image before static analysis becomes meaningful.
+- when execution is silent, inspect exit status and side effects and trace the relevant path; do not repeatedly rerun with random input.
+
+## completion
+
+the result is complete when the recovered logic or data is independently reproduced, not when a likely function or interesting string has merely been identified.

package/src/agent-skills/library/crypto-solving/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: crypto-solving
+description: "Workflow for cryptography challenges and custom encoding: formalize the construction, identify exploitable structure, implement attacks, and validate recovered plaintext or keys. Use for classical ciphers, RSA/ECC mistakes, symmetric misuse, PRNG attacks, hashes/MACs, secret sharing, lattice-style tasks, or layered encodings."
+---
+
+# crypto solving
+
+model the exact construction before choosing an attack.
+
+1. extract all known values, unknowns, equations, encodings, lengths, randomness assumptions, and attacker capabilities from source and output. preserve byte-versus-text and endian boundaries.
+2. identify the primitive and the implementation weakness separately. the name of a cipher does not establish the vulnerability.
+3. test the simplest structural explanation first: classical transformation, reused nonce/keystream, weak randomness, small parameter, oracle, algebraic relation, truncation, or encoding confusion.
+4. create a small script that reproduces the known output before using it to recover unknown values. validate intermediate equations on toy or supplied samples.
+5. use brute force only after bounding the search space and exploiting every available constraint. report the actual tested space and stopping condition.
+
+## recovery
+
+- plausible but unreadable plaintext: re-check alphabet, offsets, block boundaries, padding, endian order, and whether another encoding layer remains.
+- attack almost works: compare the implementation line by line with the mathematical assumption; challenge code often differs from the standard primitive in one decisive detail.
+- multiple candidates: use format-independent constraints or re-encryption, not an assumed flag prefix alone, to select the answer.
+
+## completion
+
+validate recovered plaintext, key material, or forged output by reversing the construction, re-encrypting, or satisfying the challenge verifier whenever possible.

package/src/agent-skills/library/ctf-solving/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: ctf-solving
+description: End-to-end workflow for solving CTF challenges and benchmark tasks across web, crypto, pwn, reversing, forensics, and misc. Use when the user asks to solve a challenge, recover a flag, or continue a stalled challenge run; combine it with one domain skill when the category is known.
+---
+
+# ctf solving
+
+drive the challenge to a validated answer, not merely an analysis report.
+
+1. identify the exact objective, supplied artifacts, reachable targets, constraints, and current working directory. verify that required files or services are actually accessible before analyzing them.
+2. classify the dominant domain from evidence, then load at most the relevant specialist skill. a mixed challenge may change domains later; do not preload every playbook.
+3. establish one concrete hypothesis and run the cheapest discriminating test. preserve useful artifacts, commands, decoded values, offsets, endpoints, and credentials as the solve progresses.
+4. when a path fails, explain what the result ruled out and change the method. do not spend the run repeating filesystem searches, scanners, decoders, or equivalent payload variants.
+5. automate repetitive transformations or interaction once the manual primitive is understood. keep scripts in the workspace when they are part of the reproducible solve.
+6. continue past reconnaissance and partial reverse engineering until the requested objective is reached or a specific missing dependency blocks progress.
+
+## completion
+
+- validate the answer against the challenge behavior or available oracle when possible.
+- do not assume a fixed flag prefix or format.
+- report the answer first, then the shortest reproducible explanation and any remaining uncertainty.
+
+## recovery
+
+- missing artifact: verify the manifest, workspace mapping, archive contents, and target lifecycle once; report the exact missing input instead of searching the entire system repeatedly.
+- insufficient tooling: use an available Kali alternative or write a focused parser/script rather than stopping at a tool name.
+- remote/local mismatch: compare architecture, libc, protocol, timing, and paths; preserve the working local primitive before adapting it.

package/src/agent-skills/library/digital-forensics/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: digital-forensics
+description: Evidence-preserving workflow for disk, filesystem, memory, archive, document, image, log, browser, and metadata forensics. Use when the task asks what happened, who acted, when an event occurred, or to recover deleted/hidden content from supplied artifacts; use packet-analysis for capture-centric evidence.
+---
+
+# digital forensics
+
+preserve provenance while reducing a large artifact set to evidence relevant to the question.
+
+1. inventory supplied artifacts, container/archive layers, sizes, timestamps, types, and hashes. work from copies or extracted views when an operation may alter metadata.
+2. translate the user question into evidence categories and a timeline: identities, execution, persistence, access, deletion, transfer, or hidden content.
+3. inspect high-signal metadata and indexes before broad carving or string searches. correlate independent sources rather than trusting one timestamp or parser.
+4. recover embedded, deleted, encoded, or renamed content with format-aware tools. verify recovered object types and relationships to the parent artifact.
+5. keep observed timestamps, normalized time zones, inferred ordering, and uncertain clock assumptions separate.
+
+## recovery
+
+- parser failure: verify file signatures, truncation, compression, encryption, and tool support; use an alternate parser or inspect the structure directly.
+- no result from a keyword search: broaden through metadata, encodings, alternate names, and timeline neighbors rather than repeating the same strings command.
+- conflicting timestamps: identify each timestamp's semantics and corroborate with logs or adjacent events.
+
+## completion
+
+answer the forensic question with a traceable artifact or correlation. absence from one parser or index is not proof that evidence never existed.

package/src/agent-skills/library/ffuf/SKILL.md

@@ -3,11 +3,11 @@ name: ffuf
 description: Wordlist strategy, soft-404 filtering, and failure recovery for directory/file fuzzing via the dir_enum tool (ffuf-backed). Use this whenever the user wants to enumerate hidden directories/files/endpoints on a web target, or mentions ffuf, gobuster, or fuzzing.
 ---
 
-# Directory Enumeration Playbook (dir_enum / ffuf)
+# directory enumeration
 
-Fuzz the `FUZZ` keyword position in the URL against a wordlist.
+use `dir_enum` for the common URL + wordlist case. use `shell_exec` with `ffuf` only when advanced matchers, filters, recursion, headers, methods, or multiple fuzz positions are required.
 
-Useful defaults:
+useful defaults:
 - Filter noisy 200s from a catch-all page: match by size/words rather than status when the
   target returns 200 for everything (soft-404) — compare a known-bad path's response size first.
 - Start with a small, common wordlist (common.txt / raft-small) before escalating to a large one —
@@ -16,7 +16,7 @@ Useful defaults:
   rather than fuzzing extensions blindly from the start.
 - Recurse only into directories that returned a real (not soft-404) response.
 
-## Failure recovery
+## failure recovery
 - All-200 responses with identical body size → soft-404 page; filter by size (`-fs <bytes>`) or
   by matching a known regex instead of status code.
 - No hits at all → verify the FUZZ position/URL is actually correct with one manual request first,

package/src/agent-skills/library/nmap/SKILL.md

@@ -3,11 +3,11 @@ name: nmap
 description: Nmap CLI syntax, safe two-pass scan patterns, and failure recovery (filtered ports, timeouts) for the nmap_scan tool. Use this whenever the user asks to port-scan, enumerate services, or check what's open on a target, even before they mention nmap by name.
 ---
 
-# Nmap Playbook
+# nmap
 
-Canonical syntax: `nmap [Scan Type(s)] [Options] {target specification}`
+use `port_scan` for the standard `-Pn -sV -sC` scan. use `shell_exec` with `nmap` when the task needs explicit ports, scan types, scripts, timing, UDP, or a deliberate two-pass workflow.
 
-High-signal flags:
+high-signal flags:
 - `-n` skip DNS resolution
 - `-Pn` skip host discovery when ICMP/ping is filtered (common in lab/VPN targets)
 - `-sS` SYN scan (needs privilege); `-sT` TCP connect scan (no raw-socket privilege needed)
@@ -18,11 +18,11 @@ High-signal flags:
 - `-T4` reasonable speed for lab targets
 - `--max-retries 1 --host-timeout 90s` bound worst-case runtime
 
-## Two-pass workflow (preferred over one giant scan)
+## two-pass workflow
 1. Fast discovery pass: `nmap -n -Pn --top-ports 100 --open -T4 --max-retries 1 --host-timeout 90s <target>`
 2. Enrichment pass on discovered ports only: `nmap -n -Pn -sV -sC -p <comma_ports> --script-timeout 30s --host-timeout 3m <target>`
 
-## Failure recovery
+## failure recovery
 - Host looks down unexpectedly → add `-Pn` (many lab/CTF targets block ICMP).
 - Scan stalls or times out → tighten `-p`/`--top-ports` and lower `--max-retries`.
 - A "filtered" result that you expect to be open may be transient (target-side rate limiting from

package/src/agent-skills/library/packet-analysis/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: packet-analysis
+description: Workflow for PCAP, PCAPNG, network-forensics, protocol-reassembly, malware traffic, and encrypted C2 challenges. Use when packet captures or recorded network streams are primary evidence; combine with binary-reversing when an extracted executable defines encoding or encryption.
+---
+
+# packet analysis
+
+turn the capture into a timeline of conversations, artifacts, and transformations.
+
+1. preserve the original capture and record its basic properties. inventory endpoints, protocols, ports, conversations, packet counts, durations, and obvious anomalies before applying narrow filters.
+2. build a timeline around the objective. identify which stream contains setup, authentication, delivery, command/control, exfiltration, or the final answer.
+3. reassemble application streams and extract transferred objects with protocol-aware tools when possible. verify extracted file type and hash before analysis.
+4. distinguish capture bytes from dissector interpretation. inspect raw stream bytes when framing, retransmission, encoding, or a custom protocol makes decoded fields misleading.
+5. if content is encoded or encrypted, locate keys and transformations in associated binaries, scripts, configuration, handshakes, or repeated structure; then implement a reproducible decoder.
+
+## recovery
+
+- no useful high-level decode: follow individual streams, inspect raw payloads, and infer framing from direction and length.
+- apparent missing data: check packet loss, truncation, out-of-order segments, retransmissions, alternate channels, and archive contents before concluding absence.
+- too much traffic: rank conversations by timing, volume, protocol, and relationship to the known event instead of applying random display filters.
+
+## completion
+
+support the answer with the relevant stream, extracted artifact, timeline, or decoder output. protocol labels and suspicious traffic alone are not the conclusion.