Cheapest, highest-value probe first.
There is no fixed service-to-action table. The agent fingerprints the exact service and version, then chooses the next tool from what it sees. Only evidence escalates it toward anything intrusive.
Know what is there before you ask what is wrong.
A range is expanded, swept for live hosts, then each one is port-scanned and its services fingerprinted to an exact product and version. All of it stays inside the target you named.
- ping_sweepLive-host discovery. With root it uses ICMP and ARP; without root it falls back to TCP-SYN probes and finds fewer hosts.
- port_scan · service_detectOpen TCP ports, then nmap version detection for service, product and version.
- os_detect · banner_grab · http_probe · dns_enumOS fingerprint (needs root), a raw banner, HTTP status and headers, and DNS records.
- NeverContacts a host outside the target, guesses a login, or writes anything to a target.
Match the version against what is known.
Once a service has an exact version, detection is about evidence, not guessing. nmap vuln scripts and thousands of nuclei templates check for known CVEs, misconfigurations and exposed panels, and an exploit search tells you which public exploits actually apply to that version.
- vuln_scannmap vulnerability NSE scripts against the open ports.
- nuclei_scannuclei CVE, misconfiguration and exposure templates over the discovered HTTP and network services.
- exploit_searchPublic exploits for the exact service and version you observed, from searchsploit or the local nuclei template index.
Detection confirms by signature, a version match, an nmap script hit or a nuclei template match. It does not fire exploits. A version string alone is noted, not reported as a vulnerability.
Read freely. Act only with consent.
Unauthenticated exposure is often the way in, and it costs nothing to check. Going active is the opposite — spraying and brute-forcing credentials, running commands over SMB/WinRM or SSH, dumping secrets, catching a reverse shell — loud, intrusive and state-changing, so each one is denied by default and never the agent's first move.
- ftp_anon · snmp_checkCheck whether anonymous FTP or a common SNMP community is open — read-only.
- cred_checkValidates one recovered credential across a host's auth services to see where it works.
consent-gated actionspassword_spray, hydra_brute, win_exec, ssh_exec, secretsdump, listener, shell_exec and exfil refuse to run unless you approve them. They are the last resort, never the default.denied by defaultResolution order: --auto-consent auto-approves, an interactive terminal prompts [y/N], and a non-interactive run auto-denies.read-only is freeDiscovery, fingerprinting, detection and domain enumeration read and change nothing on a target; only the gated actions touch state.the agent cannot self-approveConsent is resolved outside the model. The agent asks with request_consent; you answer.Reach for nmap directly, within limits.
When a case needs a scan the named tools do not cover, the agent can call nmap directly. The call still runs through the same scope lock, and whole categories of intrusive scripts are blocked no matter what the model asks for.
run_nmap refuses the brute, dos and exploit NSE categories. The blocklist lives in the tool, not the prompt, so no wording gets around it.
run_nmap("10.0.0.5", args="-sV --script ssl-enum-ciphers") # allowed: read-only script, host in scope run_nmap("10.0.0.5", args="--script brute") # refused: brute is an intrusive NSE category run_nmap("10.0.0.9", args="-sV") # refused: 10.0.0.9 is outside the target
A live map, not a database.
As tools return, pwner builds a network map in memory, hosts to open ports to service and version to findings. It is an ephemeral view for the session, shown with /topology, not a stored graph you query later.
Bookkeeping tools keep the run coherent: note records reasoning, report_finding records a confirmed finding, get_findings reads them back, and request_consent asks you before anything intrusive. None of them touch the network.
network ├─ 10.0.0.5 │ ├─ 22 ssh OpenSSH 8.9 │ ├─ 80 http nginx 1.18 │ └─ [HIGH] exposed admin panel └─ 10.0.0.8 └─ 445 smb
Findings, with evidence and a fix.
A finding carries a severity, the host and service, the concrete evidence that confirmed it, a confidence, and a remediation. The run ends with a short executive summary. The same findings print to the terminal and, with a flag, to JSON.
terminalFindings ranked by severity, plus an executive summary.--jsonThe findings and summary as a JSON object for your own tooling.There is no SARIF export, no stored graph database and no audit-log file. Output is the findings report and the in-session map.
[HIGH] exposed admin panel host: 10.0.0.5:80 service: http nginx 1.18 confidence: confirmed evidence: nuclei template match, 200 on /admin fix: restrict the panel, require auth
sample data Fictional lab host, illustrative finding.
Prove the boundary, not the port.
Two of the things PCI DSS v4.0.1 asks for are pure network-layer work. segmentation_test answers 11.4.5, and 11.4.6 on the six-month service-provider cycle: run it from a segment that is out of scope for the CDE, and it reports whether the boundary held. pci_retest answers the repeat half of 11.4.4 by re-probing findings already on the record.
It is not asking what a port scan asks. A port scan wants to know what is listening; this wants to know whether a packet can arrive at all, so a closed port that answers with a RST is a failure of isolation rather than a pass — something on the path replied.
A TCP connect cannot tell a host RST from a firewall reject, so that case is reported as inconclusive instead of guessed in either direction, and an inconclusive probe is never filed as a finding. Calling it a pass would manufacture evidence of a boundary that was never demonstrated; calling it a failure would invent one. Settle those from the segmentation control's own logs.
This does not make anyone compliant. 11.4.2 and 11.4.3 require a qualified tester with organizational independence, 11.4.1 requires a documented methodology, and the quarterly external scan in 11.3.2 has to come from an Approved Scanning Vendor. These are instruments a tester uses; what they add is the evidence an assessor asks for — when, from where, against what, and what came back.
$ pwner pci 10.0.0.0/24 CDE 10.0.0.0/24 vantage point 192.168.9.9 tested at 2026-11-04T13:40:11Z coverage 254 hosts x 19 ports = 4826 probes VERDICT not isolated reachable — isolation failed here (1): 10.0.0.5:3306 open inconclusive — something answered (2): 10.0.0.9:445 refused
sample data Fictional CDE range. Being deterministic is the point: re-running the same command after a fix is the retest 11.4.4 asks for, and the exit code makes it a gate.
A tool is a Python function.
There is no plugin SDK, WASM sandbox or manifest format. A new tool is an async Python function registered in the agent's dispatch table with a small JSON schema the model sees. The same scope lock wraps it like every other tool.
Anything intrusive a new tool does should route through request_consent: read freely, ask before you act.
# one declaration site: @tool registers it, advertises it to the # model, makes it dispatchable and scope-guards it, all at once. @tool("What the model should know about this tool.", {"host": {"type": "string"}}, ["host"]) async def my_check(ctx, args): host = args["host"] # scope was already checked before this body ran return {"host": host, "result": ...}
What each tool reads and never does.
Access is what the tool needs beyond a read: read-only is the default, consent needs your approval, root needs privileges. Names track the current build.
| Tool | Reads | Never | Access |
|---|---|---|---|
| ping_sweep | Host liveness, via ICMP and ARP with root, TCP-SYN without | Contacts an address outside the target range | read-only |
| dns_enum | DNS records for a domain | Writes a zone or abuses a transfer | read-only |
| port_scan | Open TCP ports on an in-scope host | Touches a host outside the target | read-only |
| service_detect | Service, product and version (nmap -sV) | Attempts a login | read-only |
| os_detect | OS fingerprint (nmap -O) | Writes or modifies the host | root |
| banner_grab | A raw banner from one port | Sends a payload or malformed input | read-only |
| http_probe | HTTP status, server, title and headers | Fuzzes or exploits the endpoint | read-only |
| content_discovery · web_request · http_download | Hidden web paths, custom HTTP requests, and full response bodies with any creds inside | Writes to the app unasked or fuzzes destructively | read-only |
| web_crawl | The app's own links and forms: every reachable path, the parameters each takes, every form and its inputs | Follows a link off the authorized target | read-only |
| dirsearch_scan | Which paths exist, from a real wordlist, grouped by response signature | Writes, or reports a catch-all server as hundreds of hits | read-only |
| param_probe | How one parameter changes the response across payload classes, measured against a clean baseline | Sends a write, a DROP or a timing payload | read-only |
| segmentation_test · pci_retest | Whether a packet can reach the CDE from here, and whether a recorded exposure is gone | Calls an ambiguous result isolated | read-only |
| tcp_send | A raw reply from any TCP service (Redis, memcached, a DB handshake) | Sends a destructive command | read-only |
| vuln_scan | nmap vulnerability-script output | Runs intrusive or exploit scripts | read-only |
| nuclei_scan | nuclei CVE, misconfig and exposure matches | Runs brute-force or denial templates | read-only |
| exploit_search | Public exploits for an observed version | Launches an exploit | read-only |
| ftp_anon | Whether anonymous FTP is allowed, and a listing | Uploads or writes | read-only |
| snmp_check | SNMP reachability with a common community | Writes an SNMP value | read-only |
| ftp_get · smb_enum · smb_shares · smb_get · ssl_info | A file over FTP or SMB, SMB shares and OS info, and a TLS certificate and ciphers | Writes or deletes on the target | read-only |
| kerbrute_userenum · asrep_roast · kerberoast | Valid domain usernames and crackable Kerberos hashes, with no account lockout | Submits a password or locks an account | read-only |
| ldap_enum · rid_brute · bloodhound_collect · adcs_find · dc_vuln_check | Domain users, groups, policy, attack paths, ADCS templates and DC-vuln signatures | Exploits a DC flaw — detection only | read-only |
| cred_check · hash_crack | Where a recovered credential works, and plaintext from a hash cracked offline | Brute-forces, or contacts the target to crack | read-only |
| password_spray · hydra_brute | Whether a sprayed or brute-forced credential logs in | Runs without your approval | consent |
| win_exec · ssh_exec | Runs a command on a Windows (SMB/WinRM) or Linux (SSH) host and reads the output | Runs without your approval | consent |
| secretsdump | Dumps SAM/LSA secrets or NTDS.dit domain hashes | Runs without your approval | consent |
| listener · shell_exec · exfil | Catches a reverse shell, runs commands in it, and reads blind-RCE output back | Runs without your approval | consent |
| run_nmap | Whatever your nmap args read, in scope | Runs brute, dos or exploit NSE categories | read-only |
| set_target | Nothing. It moves the scope itself | Widens past what you authorized without asking you | consent |
| ledger · note · report_finding · get_findings · request_consent · attacker_info | The run's own ledger, notes, findings, consent state and your reachable IP | Touches the target | local |