TOOLSscope-locked, consent-gated, called on demand

Read freely. Act with consent.

pwner wraps nmap, nuclei, netexec, impacket, hydra and friends behind a set of small tools the agent calls as it reasons. Every one is locked to the target you named, enforced at the tool layer outside the model. Discovery, fingerprinting and detection read freely; credential attacks, exploitation, remote command execution, reverse shells and credential dumping are denied until you approve them. This page groups the tools, shows what each reads or does, and marks the ones that need more than a read: root, or your consent.

Authorized testing only. Every tool refuses any host outside your target, and everything active is denied until you approve it. Read the rules

  1. discoveryread-only
  2. fingerprintread-only
  3. detectionread-only
  4. anon accessread-only
  5. active directoryread-only
  6. credentialsconsent
  7. exploitationconsent
  8. raw nmapguarded
scope checks every call first
Left column, the tool groups. Right column, what they cost.
APPROACHevidence picks the next tool

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.

The order the agent prefers: anonymous and version checks, then known-CVE lookups for that exact version, then default or weak credentials, then spraying or brute-force if the target warrants it — and active exploitation (RCE, shells, secrets) only once you approve it.
DISCOVERY, FINGERPRINTread-only

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.
~/engagements/acme-demosample, fictional lab
sample data, fictional lab. Output is stylized.
DETECTIONread-only, grounded in the version you observed

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.

~/engagements/acme-demosample, fictional lab
sample data, fictional lab. Output is stylized.
ANONYMOUS ACCESS, EXPLOITATIONsome read, some are gated

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.
RAW NMAPan escape hatch with the sharp edges blocked

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.

guarded callexample
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
THE MAPbuilt as the agent goes

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 map/topology
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
REPORTINGwhat it confirms, two ways

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.

findingexample
[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.

PCI DSSsegmentation, not a port scan

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 pcino model, deterministic
$ 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.

ADDING A TOOLhonest and small

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.

a tool, sketchedexample
# 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": ...}
REFERENCEevery tool, one row

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.

Tools, what they read, what they never do, and what access they need
ToolReadsNeverAccess
ping_sweepHost liveness, via ICMP and ARP with root, TCP-SYN withoutContacts an address outside the target rangeread-only
dns_enumDNS records for a domainWrites a zone or abuses a transferread-only
port_scanOpen TCP ports on an in-scope hostTouches a host outside the targetread-only
service_detectService, product and version (nmap -sV)Attempts a loginread-only
os_detectOS fingerprint (nmap -O)Writes or modifies the hostroot
banner_grabA raw banner from one portSends a payload or malformed inputread-only
http_probeHTTP status, server, title and headersFuzzes or exploits the endpointread-only
content_discovery · web_request · http_downloadHidden web paths, custom HTTP requests, and full response bodies with any creds insideWrites to the app unasked or fuzzes destructivelyread-only
web_crawlThe app's own links and forms: every reachable path, the parameters each takes, every form and its inputsFollows a link off the authorized targetread-only
dirsearch_scanWhich paths exist, from a real wordlist, grouped by response signatureWrites, or reports a catch-all server as hundreds of hitsread-only
param_probeHow one parameter changes the response across payload classes, measured against a clean baselineSends a write, a DROP or a timing payloadread-only
segmentation_test · pci_retestWhether a packet can reach the CDE from here, and whether a recorded exposure is goneCalls an ambiguous result isolatedread-only
tcp_sendA raw reply from any TCP service (Redis, memcached, a DB handshake)Sends a destructive commandread-only
vuln_scannmap vulnerability-script outputRuns intrusive or exploit scriptsread-only
nuclei_scannuclei CVE, misconfig and exposure matchesRuns brute-force or denial templatesread-only
exploit_searchPublic exploits for an observed versionLaunches an exploitread-only
ftp_anonWhether anonymous FTP is allowed, and a listingUploads or writesread-only
snmp_checkSNMP reachability with a common communityWrites an SNMP valueread-only
ftp_get · smb_enum · smb_shares · smb_get · ssl_infoA file over FTP or SMB, SMB shares and OS info, and a TLS certificate and ciphersWrites or deletes on the targetread-only
kerbrute_userenum · asrep_roast · kerberoastValid domain usernames and crackable Kerberos hashes, with no account lockoutSubmits a password or locks an accountread-only
ldap_enum · rid_brute · bloodhound_collect · adcs_find · dc_vuln_checkDomain users, groups, policy, attack paths, ADCS templates and DC-vuln signaturesExploits a DC flaw — detection onlyread-only
cred_check · hash_crackWhere a recovered credential works, and plaintext from a hash cracked offlineBrute-forces, or contacts the target to crackread-only
password_spray · hydra_bruteWhether a sprayed or brute-forced credential logs inRuns without your approvalconsent
win_exec · ssh_execRuns a command on a Windows (SMB/WinRM) or Linux (SSH) host and reads the outputRuns without your approvalconsent
secretsdumpDumps SAM/LSA secrets or NTDS.dit domain hashesRuns without your approvalconsent
listener · shell_exec · exfilCatches a reverse shell, runs commands in it, and reads blind-RCE output backRuns without your approvalconsent
run_nmapWhatever your nmap args read, in scopeRuns brute, dos or exploit NSE categoriesread-only
set_targetNothing. It moves the scope itselfWidens past what you authorized without asking youconsent
ledger · note · report_finding · get_findings · request_consent · attacker_infoThe run's own ledger, notes, findings, consent state and your reachable IPTouches the targetlocal