Getting started¶
What you need¶
- Go 1.24 or newer
- Nmap, installed and on your PATH (
brew install nmaporsudo apt install nmap)
Build¶
git clone https://github.com/nuqs-org/nuqs.git
cd nuqs
go build -o nuqs ./cmd/nuqs
./nuqs version
Run a scan¶
./nuqs scan 192.168.1.1
You can give one or more targets:
| Target | Example |
|---|---|
| One IP | 192.168.1.1 |
| A network | 192.168.1.0/24 |
| A range (last part only) | 192.168.1.10-20 |
| A hostname | router.lan |
Only scan what you own
Scanning other people's networks without permission is illegal in most places.
Useful flags¶
Flags can go before or after the targets.
| Flag | What it does |
|---|---|
-p 22,80,443 |
Scan only these ports (default is Nmap's top 1000) |
-Pn |
Scan hosts even if they don't answer ping |
--json |
Print the report as JSON instead of text |
--workers 10 |
How many checks run at the same time |
--timeout 30s |
Max time for one check |
--force |
Allow scanning more than 1024 addresses |
--nmap /path/to/nmap |
Use a specific Nmap binary |
Reading the output¶
Progress goes to stderr and the report goes to stdout, so ./nuqs scan --json 10.0.0.1 > report.json gives you a clean JSON file.
Every finding has:
- Severity, from info to critical
- Evidence, what we actually saw, so you can check it yourself
- Fix, what to do about it
If a check couldn't finish (timeout, connection reset and so on), it's listed under "Checks that could not finish". That's not a finding, it just means we couldn't tell.
Exit codes¶
| Code | Meaning |
|---|---|
| 0 | Scan finished (with or without findings) |
| 1 | Scan couldn't run, or was stopped |
| 2 | The command was typed wrong |
Other commands¶
./nuqs checks # list the built-in checks
./nuqs version # print the version