Architecture¶
This page is generated
tools/archdiagram builds it from the code on every push, so it always matches what's in the repo. Don't edit it by hand. Every description comes from the file itself: the package doc comment for folders, and the one-line comment at the top of each file.
How the packages connect¶
An arrow means "uses". For example internal/cli --> internal/engine means the CLI calls the engine.
flowchart LR
subgraph n_g_checks ["checks"]
n_checks["checks"]
n_checks__["checks/*<br/><small>ftpanon, httpheaders, redisnoauth, telnet</small>"]
end
subgraph n_g_cmd ["cmd"]
n_cmd_nuqs["cmd/nuqs"]
end
subgraph n_g_internal ["internal"]
n_internal_check["internal/check"]
n_internal_cli["internal/cli"]
n_internal_engine["internal/engine"]
n_internal_model["internal/model"]
n_internal_nmap["internal/nmap"]
n_internal_output["internal/output"]
n_internal_target["internal/target"]
n_internal_version["internal/version"]
end
subgraph n_g_lab ["lab"]
n_lab["lab"]
end
subgraph n_g_tools ["tools"]
n_tools_apidocs["tools/apidocs"]
n_tools_archdiagram["tools/archdiagram"]
end
n_checks --> n_checks__
n_checks --> n_internal_check
n_checks__ --> n_internal_check
n_checks__ --> n_internal_model
n_cmd_nuqs --> n_checks
n_cmd_nuqs --> n_internal_cli
n_cmd_nuqs --> n_internal_nmap
n_internal_check --> n_internal_model
n_internal_cli --> n_internal_check
n_internal_cli --> n_internal_engine
n_internal_cli --> n_internal_nmap
n_internal_cli --> n_internal_output
n_internal_cli --> n_internal_target
n_internal_engine --> n_internal_check
n_internal_engine --> n_internal_model
n_internal_nmap --> n_internal_model
n_internal_output --> n_internal_engine
n_internal_output --> n_internal_model
n_lab --> n_internal_model
Packages¶
| Package | What it does | Uses |
|---|---|---|
checks |
Lists every check that ships with Nuqs. | checks/ftpanon, checks/httpheaders, checks/redisnoauth, checks/telnet, internal/check |
checks/ftpanon |
Checks if an FTP server lets anyone log in as "anonymous". | internal/check, internal/model |
checks/httpheaders |
Checks web servers for missing security headers. | internal/check, internal/model |
checks/redisnoauth |
Checks if a Redis server allows unauthenticated access. | internal/check, internal/model |
checks/telnet |
Flags open Telnet services. | internal/check, internal/model |
cmd/nuqs |
The Nuqs vulnerability assessment tool. | checks, internal/cli, internal/nmap |
internal/check |
Defines what a check is. | internal/model |
internal/cli |
The "nuqs" command line. | internal/check, internal/engine, internal/nmap, internal/output, internal/target |
internal/engine |
Runs a scan from start to end. | internal/check, internal/model |
internal/model |
Holds the small set of types that every part of Nuqs shares. | nothing else in Nuqs |
internal/nmap |
Runs Nmap and turns its XML output into model.Host values. | internal/model |
internal/output |
Prints a scan report, either as a table for people or as JSON for tools. | internal/engine, internal/model |
internal/target |
Checks what the user asked us to scan before it ever reaches Nmap. | nothing else in Nuqs |
internal/version |
Compares software versions the way each ecosystem does. | nothing else in Nuqs |
lab |
Validates and fixes the two timestamps in a Nuqs JSON report, and drops Nmap's product guess for the Telnet server, which changes between runs. | internal/model |
tools/apidocs |
Writes the API reference pages of the website, one page per package, from the doc comments in the code. | nothing else in Nuqs |
tools/archdiagram |
Writes docs/architecture.md, a diagram and a map of the repo built straight from the code. | nothing else in Nuqs |
What's where¶
Every file in the repo, as git sees it, except the docs/ and test/ folders. Click a folder to open or close it.
.github/GitHub settings.workflows/CI jobs. They run on every push and pull request.ci.ymlTests, lint, fuzzing, the real Nmap test and builds, on every push and pull request.docs.ymlBuilds the docs website on every pull request and publishes it from the default branch.
pull_request_template.mdThe template every new pull request starts with.
checks/Lists every check that ships with Nuqs.ftpanon/Checks if an FTP server lets anyone log in as "anonymous".ftpanon.goftpanon_test.goTests the FTP check against a small fake FTP server.
httpheaders/Checks web servers for missing security headers.httpheaders.gohttpheaders_test.goTests the web headers check against local test servers.
redisnoauth/Checks if a Redis server allows unauthenticated access.redisnoauth.goredisnoauth_test.goTests the Redis unauthenticated access check against fake Redis servers.
telnet/Flags open Telnet services.telnet.gotelnet_test.goTests the Telnet check.
checks.gochecks_test.goMakes sure every built-in check is valid, tested and listed.
cmd/Programs you can run. Each folder here is one binary.nuqs/The Nuqs vulnerability assessment tool.main.go
internal/The core of Nuqs. Only code in this repo can import these.check/Defines what a check is.check.gocheck_test.goTests when checks apply and how check lists are validated.
cli/The "nuqs" command line.testdata/Sample files used by the tests next to it (1 file).cli.gocli_test.goRuns the whole CLI with a fake Nmap, so no network is needed.
engine/Runs a scan from start to end.engine.goengine_test.goTests the engine: timeouts, panics, cancelling, the worker limit and sorting.
model/Holds the small set of types that every part of Nuqs shares.model.gomodel_test.goTests severities, finding IDs and the JSON shape.
nmap/Runs Nmap and turns its XML output into model.Host values.testdata/Sample files used by the tests next to it (1 file).nmap.gonmap_test.goTests building the Nmap command, reading its XML and running it.
output/Prints a scan report, either as a table for people or as JSON for tools.output.gooutput_test.goTests the text and JSON reports.
target/Checks what the user asked us to scan before it ever reaches Nmap.target.gotarget_test.goTests target parsing and the safety limit, and fuzzes it with random input.
version/Compares software versions the way each ecosystem does.debian.goDebian and Ubuntu package versions, compared like dpkg does.debian_test.goTest cases for Debian versions.helpers.goSmall helpers shared by the schemes.openssh.goOpenSSH versions like 9.6p1, as banners and Nmap show them.openssh_test.goTest cases for OpenSSH versions.rpm.goRed Hat, Fedora, SUSE and other RPM package versions, compared like rpm does.rpm_test.goTest cases for RPM versions.semver.goSemantic versioning, like 1.2.3 and 1.0.0-rc.1.semver_test.goTest cases for semver.version.goversion_test.goTests shared by every scheme: ordering, bad input, lookup and a fuzz test.
lab/Validates and fixes the two timestamps in a Nuqs JSON report, and drops Nmap's product guess for the Telnet server, which changes between runs.ftp/DockerfileBuilds the public FTP handshake fixture used in the lab.vsftpd.confAllows a public handshake with an empty directory and no file transfers.
docker-compose.ymlRuns the three loopback services for the Nuqs report test.expected-report.jsonindex.htmlnginx.confServes a static page with a read-only root filesystem.normalize.gonormalize_test.goTests the timestamp normalization used by the lab report comparison.
scripts/Small helper scripts used by CI.docs.shBuilds the docs website.lab.shBuilds Nuqs and compares its report for the loopback lab services with the golden file.
tools/Helper programs for developing Nuqs. Not part of the scanner.apidocs/Writes the API reference pages of the website, one page per package, from the doc comments in the code.testdata/Sample files used by the tests next to it (7 files).apidocs.goFinds the packages, reads their docs and writes one Markdown page each.apidocs_test.goTests for the API page generator, run against a small fake module.main.go
archdiagram/Writes docs/architecture.md, a diagram and a map of the repo built straight from the code.testdata/Sample files used by the tests next to it (11 files).arch.goReads the repo: its packages, what they import, and its files.arch_test.goTests the generator, and checks it against go list so the diagram is always right.main.gonotes.goReads the one-line description at the top of each file.notes_test.goTests reading the one-line description at the top of each kind of file.render.goTurns what we read into the architecture page: diagram, table and file tree.
.gitignoreFiles git should ignore, like build output and generated docs..golangci.ymlLint settings.LICENSEREADME.mdThe front page of the repo: what Nuqs is and how to start.SECURITY.mdHow to report a security problem in Nuqs.go.modThe Go module for Nuqs.mkdocs.ymlSettings for the docs website (MkDocs Material).