Skip to content
NICE-DEV226Public

About

Evidence-first web security scanner — proof or nothing. DAST with provenance grades, two-session BOLA, OpenAPI grey-box, JS surface discovery, SARIF CI gating. MIT, single Go binary, air-gap ready.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

nice_scan

CI status Latest release Go 1.24+ MIT license Security policy

A defensive-first reconnaissance and validation CLI for authorized security work.
Fast HTTP scanning · technology fingerprinting · an evidence-driven decision engine that chains checks and proves what it claims.


nice_scan is a command-line tool for authorized security testing. It performs reconnaissance, fingerprinting, and controlled validation of common web vulnerabilities, then reports each result at the confidence the evidence actually supports. It is built to be honest: a finding states whether it was executed and server-verified, merely observed, or an untested hypothesis — so a report tells you what is real, not what is scary.

Use only on systems you own or are explicitly authorized to test. See Responsible use.

nice_scan terminal output on a live target — findings grouped by severity with confidence and evidence

Table of contents

Why this design

Most scanners drown operators in keyword matches. nice_scan ties every claim to a concrete verification state:

Verdict What it means How it earns the label
Confirmed Server-verified A probe was executed and the target's response carries structural proof (an error oracle, a marked command's output, a canary reflected in an executable context, a session cookie issued only on a valid login).
Observed Seen on the target, not exploited A real signal was directly fetched (a login form, an upload field, a set of exposed headers) with no state-changing action run over it.
Hypothesis A chain the engine would attempt Reported as a plan, never as a breach.

Two rules follow from this:

  1. Differential baselines, not single responses. A claim compares against a control (a junk-credential round, an anonymous request, the endpoint's own modal response size) so the verdict rests on a delta, not a status code.
  2. Consent gates state changes. Login spray, role/privilege tampering, account registration, discovered-credential attempts, and file/command probes modify target state. They are disabled unless you pass --destructive (or enable consent on in the shell).

Capabilities

Area What nice_scan does
Reconnaissance Passive sources (crt.sh, Wayback) that send zero requests to the target · BFS crawl of pages, forms, and JS · path fuzzing · concurrent TCP port scan · S3 bucket enumeration
Fingerprinting 165 technology signatures, version extraction, and stack classification cached per target
Validation SQLi detection with a differential oracle · LFI detection and bounded file read · canary-based XSS reflection with context classification · login validation against a junk baseline · JWT analysis · GraphQL introspection
Decision engine Forward-chaining planner · knowledge base with capability derivation · session/context reuse · attack-chain patterns surfaced as hypotheses
Output Terminal report with severity and confidence · live TUI dashboard · interactive REPL shell · JSON and SARIF 2.1.0 for pipelines · HTML engagement report with a findings timeline and evidence

Installation

nice_scan ships through GitHub Releases and go install only. There is no Homebrew tap, Scoop bucket, or Winget identity; any brew install, scoop install, or winget install command you see elsewhere targets package IDs this project does not own and is not maintained here.

The installers are fail-closed: they resolve a single release tag, verify the SHA256 checksum and the GPG signature over checksums.txt first, and abort with nothing installed if any step fails.

Linux and macOS

curl -sfL https://raw.githubusercontent.com/NICE-DEV226/nice-Scan/main/scripts/install.sh | sh

# The installer drops nice_scan in ~/.local/bin and records it in your shell rc.
# For the CURRENT terminal, pick it up without reopening:
export PATH="$HOME/.local/bin:$PATH"

nice_scan --help

The installer places the binary in ~/.local/bin (or, if it builds via go install, in $(go env GOPATH)/bin) and appends that directory to your PATH in the shell rc file it finds (.zshrc / .bashrc / .zprofile / .profile), so new terminals find it automatically. If you installed through the go install path, export that directory instead:

export PATH="$PATH:$(go env GOPATH)/bin"

nice_scan "disappears" after a reboot? It is on disk — it simply is not on that login shell's PATH. Re-run the export above (or the installer) and it is reachable again. The current installer writes the PATH line into your rc files so the install survives a restart.

From source with Go (1.24+)

go install github.com/NICE-DEV226/nice-Scan/cmd/nice_scan@v0.3.7

Pin the tag, not @latest. @latest resolves main's head commit, which stamps a pseudo-version (v0.3.7-0.2026…-hash) — nice_scan update then has no release to compare against and refuses without --force, so you would be reinstalling by hand forever. A tagged install self-updates normally.

Windows (PowerShell 7+)

Invoke-WebRequest https://raw.githubusercontent.com/NICE-DEV226/nice-Scan/main/scripts/install.ps1 -OutFile install.ps1
pwsh -ExecutionPolicy Bypass -File install.ps1

Manual download

Download the archive for your platform from the Releases page, verify it (see Release verification), and install it anywhere on your PATH — for example /usr/local/bin on Linux/macOS.

Air-gapped / on-premise install

Hosts with no route to github.com can be provisioned entirely offline: copy the release archive plus checksums.txt (and checksums.txt.sig if you want signature verification) onto the machine — USB, internal artifact share, whatever your process allows — then:

install.sh --archive nice_scan_0.3.7_linux_amd64.tar.gz \
           [--checksums checksums.txt] [--sig checksums.txt.sig]

The same fail-closed rules apply: the checksums file is mandatory and must cover the archive, and a supplied signature must verify against the pinned release key already present in the local keyring (an offline host cannot fetch it — import it from a trusted channel beforehand, see SECURITY.md). Once installed, disable the update check so the tool never tries to reach out:

nice_scan --no-update-check        # or: NICE_SCAN_NO_UPDATE_CHECK=1

Everything else is self-contained: single Go binary, no cloud service, no telemetry, reports written locally with 0600 permissions.

Build from source

git clone https://github.com/NICE-DEV226/nice-Scan.git
cd nice-Scan
go build -o nice_scan ./cmd/nice_scan

Quick start

# Autonomous reconnaissance + validation, with an HTML engagement report
nice_scan hack example.com -R report.html

# Standard scan with a live dashboard
nice_scan scan example.com -i

# Deep audit: verbose, every module in detail, HTML report on by default
nice_scan audit example.com

# Fingerprinting and TLS analysis only
nice_scan tech example.com
nice_scan tls https://example.com

# Targeted exploitation modules (non-destructive by default)
nice_scan exploit https://example.com --idor 1-100 --token

# Interactive REPL shell
nice_scan shell

Time-box a run and prove you consented to state-changing checks:

nice_scan hack example.com --timeout 30s -R report.html --destructive

Commands

Command What it does Example
hack <target> Autonomous bounded chain — recon, fingerprint, validation, forward-chaining on verified capabilities, OOB blind detection. --destructive unlocks state-changing actions nice_scan hack https://app.example.com -R report.html
scan <target> Standard scan — fingerprint, headers, TLS, exposures, JS-bundle surface discovery, OpenAPI-guided probes, two-session BOLA nice_scan scan https://app.example.com --openapi spec.yaml --sarif out.sarif
audit <target> Everything scan does plus verbose module detail and a written HTML report nice_scan audit https://app.example.com
exploit <target> Individual modules — --login (differential credential verdicts), --idor, --privesc, --register, --reset, --session, --token. State-changing modules refuse without --destructive nice_scan exploit https://app.example.com --login --destructive
tech <target> Technology fingerprinting only (165 signatures) nice_scan tech https://app.example.com
tls <target> TLS analysis — negotiated version, certificate SANs/issuer nice_scan tls app.example.com
subdomains <domain> Passive enumeration via crt.sh, Wayback, GitHub dorks — zero requests to the target nice_scan subdomains example.com
shell Interactive REPL across targets — history, consent toggle, scope enforced per command nice_scan shell
update Self-update, checksum-verified, previous binary kept as nice_scan.old nice_scan update

Authenticated differential (BOLA/IDOR): give scan two identities and sessions and it replays object URLs under both, reporting only on a positive identity marker — never on "both got 200":

nice_scan scan https://app.example.com \
  --identity-a "alice@example.com" --identity-b "bob@example.com" \
  --session-a "Cookie: sid=A" --session-b "Cookie: sid=B"

Grey-box spec: point scan at an OpenAPI 3.x document (JSON or YAML) and its declared paths become probes — SPA/API routes a crawler cannot reach. Read-only methods only; capped at 150 probes.

CI gate: --sarif emits SARIF 2.1.0 for GitHub Code Scanning / GitLab / Azure DevOps; --fail-on-severity exits non-zero at or above a threshold. A composite GitHub Action ships at the repo root (action.yml).

Global flags

Flag Default Description
-w, --workers <n> 64 Concurrent workers
--timeout <dur> config Per-request timeout (e.g. 10s)
--retries <n> config Max retries per request
--rate-limit <n> 0 Requests per second (0 = unlimited)
--proxy <url> — HTTP proxy URL
--cookie <value> — Cookie header included in every request
--header key:value — Custom header, repeatable
--follow-redirects true Follow redirects
--max-redirects <n> 5 Redirect hop limit
--allow-out-of-scope false Turn the target boundary off. By default the target host is a hard limit: a request aimed at another host is refused before anything goes on the wire, and a redirect that leaves it aborts (credentials were already stripped there; the probe itself is now refused too). Use this for a site whose redirects legitimately land on another domain. Passive sources (crt.sh, Wayback) and the OOB callback sink have their own clients and are unaffected
--block-internal false Refuse to dial addresses that are not globally routable: loopback, RFC1918, link-local (so 169.254.169.254), CGNAT. The name is resolved and the resolved literal is dialled, which also defeats a hostname pointing inward. Off by default — scanning your own dev server is a legitimate use. Silently disabled under a proxy, which sees the destination instead of us
-j, --json false Machine-readable JSON output
-i, --interactive false Live TUI dashboard
-R, --report <file> — Write a detailed HTML report
--client-report <file> — Write a client-facing assessment report (executive summary, findings with proof + remediation, print-to-PDF ready). Same 0600 permissions
--sarif <file> — Write a SARIF 2.1.0 report (- for stdout) — feeds GitHub Code Scanning, GitLab and Azure DevOps; scan/audit only
--fail-on-severity <sev> — Exit non-zero when a finding at or above info|low|medium|high|critical exists — CI gate
--identity-a <id> / --identity-b <id> — Private identifiers (email/internal id — never public usernames) for the two-session BOLA differential
--session-a <hdr> / --session-b <hdr> — Per-session header, Name: value, repeatable (e.g. --session-a 'Cookie: sid=A'). All four flags together arm the cross-session object-access check
--openapi <file> — OpenAPI 3.x spec (JSON/YAML) — declared paths become scan probes for SPA/API coverage. Read-only methods only (GET/HEAD/OPTIONS); path params → 1, required query params → test; capped at 150 probes
-v, --verbose false Verbose output
--destructive false Consent to state-modifying actions (login spray, role tamper, registration, discovered-credential attempts). Required to enable them; targets must be authorized
--no-update-check false Disable the automatic new-release check (also NICE_SCAN_NO_UPDATE_CHECK=1)
--version — Print the version

GitHub Action — scan on every PR

The repo ships a composite action at the root, so uses: works with no subdirectory. It downloads the pinned release binary, verifies SHA256 against the published checksums (fail-closed, same rule as the installers), runs the scan, uploads SARIF to code scanning, then applies the severity gate — the report is never lost to a failing gate.

name: Security scan
on:
  pull_request:
  schedule: [{ cron: "0 6 * * 1" }]

permissions:
  security-events: write   # required for the SARIF upload

jobs:
  nice-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: NICE-DEV226/nice-Scan@v0.3.7
        with:
          target: https://staging.example.com   # staging/dev, never prod
          fail_on_severity: high
          version: v0.3.7                        # pin the release you trust
Input Default Purpose
target — (required) URL to scan
command scan scan or audit
version latest Release tag or latest
sarif_file nice-scan-results.sarif Output path
fail_on_severity — Gate the job at info…critical
extra_args — Extra flags (--destructive, --cookie …)
timeout — Per-request timeout
upload_sarif true Upload to code scanning
category nice_scan Code-scanning category

A minimal copy-paste workflow lives in examples/github-action-scan.yml.

The exploit modules

Non-destructive by default. Modules that modify target state refuse to run without --destructive.

The boundary is enforced in the package, not only by the flags: exploit.NewService refuses to exist without an explicit target scope and takes consent from Config.Destructive (the --destructive flag), so a script, the shell or a model driving the library inherits the destination allow-list and the consent gate instead of copying the CLI's checks. The state-changing entry points return ErrConsentRequired before they build a request — a refusal costs the target zero bytes.

Flag Module Consent
--idor <start-end> IDOR enumeration with a per-endpoint modal baseline (only referents that differ from their own endpoint are flagged) no
--token Token/session reuse on protected endpoints — tokens are harvested from the target; nothing is invented, and an empty harvest is reported honestly no
--session Session cookie hardening on login surfaces (Secure/HttpOnly, ID entropy). Fixation needs a credentialed login and is reported as not tested no
--reset Password-reset flows — user enumeration split and token leaks; sends live mail and can mint tokens yes
--access Replays admin paths anonymously vs. with the session — a differential access check; reports real gains or states plainly that nothing was verified no
--creds user:pass Attempt a specific credential pair, then attach the session to --access verification no*
--login Credential spray against login forms, verdict differential vs. a junk baseline yes
--role Role/privilege escalation via parameters and headers (tampered requests) yes
--register Account registration testing (creates state) yes
--all Run every module; the destructive ones still require --destructive mixed

* An operator-supplied credential is not sprayed at the target beyond the single attempt; automatic exploitation of discovered leaked credentials is consent-gated.

The hack chain

hack is the autonomous path: a planner picks the next action from the evidence it has and chains forward. It runs through hacker.NewService, which owns the same two decisions as exploit: an explicit target scope (refused with ErrNoScope), a client built from the operator's config (EnforceScope, BlockInternal, proxy, rate limit), and consent read from Config.Destructive.

Destructive modules stay registered so the report can name them as withheld — at the planner dispatch point, on runtime-spawned actions, and on chains that execute outside the planner. A chain the gate skips is listed, not silently dropped.

The non-HTTP probes obey the same boundary: transport.ProbeHost vets a host once (scope first, then resolve + private-network guard) and the port scanner and TLS inspector dial the vetted literal, never the name. A refused host becomes a probe_refused / tls_refused finding, so a report never reads "nothing open" when the truth is "nothing was probed".

hack -j emits one JSON document on stdout with no progress lines; findings go through the same redaction rule as the JSON engine sink, and credentials are masked (username filtered, password replaced by its length).

Output and reporting

hack and audit render a terminal report grouped by severity, with a confidence value and an evidence line for each finding. Use --json for machine consumption and -R report.html for a shareable engagement report (risk score, findings timeline, evidence). Extracted artifacts are written under reports/<target>/ with restrictive 0700 permissions.

Every finding name and evidence is run through sanitization, and plaintext secrets are masked by default (the provider prefix and the length are preserved, the value is not) so credentials never leak into terminal scrollback, JSON, or the HTML report. Masking happens where the credential is found, not only where it is printed: a truncated session token is still the beginning of a live session token.

--json is the machine-facing path and prints nothing but the report — no banner — so it can be piped straight into jq or into a model. Each finding carries a grade (proven > corroborated > indicated > unverified) and, where the engine earned one, a prov object naming the request, whether the path was observed or synthesized, and the differential the claim rests on. That is what lets an automated consumer rank findings without a human re-reading every evidence line, and it is why the same masking rules apply there.

The snippet below is illustrative — actual findings depend on the target. It shows the point of the design: nice_scan records an escaped reflection but does not inflate it into an executable-XSS claim, because encoded markup cannot run as reflected.

◈ MEDIUM
  ⚠  Session cookie missing HttpOnly                         92% confidence
     Set-Cookie: sid=<masked len=32>; Secure

◈ LOW
  ○  XSS reflection (escaped)                                45% confidence
     search=&lt;svg onload=alert(…)&gt;   (entity-encoded — does not execute)

The --client-report output is a standalone, print-ready HTML document — cover block, risk banner, severity table, and numbered findings (F-001…) each with its proof, provenance grade, and remediation. No external assets; it opens anywhere and exports cleanly to PDF.

Client report cover and findings — professional assessment document layout

Supply chain and release integrity

Layer Status How to verify
Binary integrity SHA256 checksums.txt published per release sha256sum --check <checksums> --ignore-missing
Release authenticity checksums.txt GPG-signed gpg --verify <checksums>.sig <checksums>
Build provenance GitHub provenance attestations for releases cut after 2026-10-24 (not retroactive) gh attestation verify <file> -R NICE-DEV226/nice-Scan
SBOM SPDX SBOM emitted per release in the release assets
Source trust Commits are not systematically GPG-signed build from a pinned tag and audit it
Distribution GitHub Releases + go install <tag> —

The pinned maintainer GPG fingerprint is 4CE466095C5B3185883288C593FBFE29F62FA4DB, imported on first use from keyserver.ubuntu.com over hkps. A key that does not match this fingerprint makes install.sh abort rather than validate an unexpected signature. The full policy, including the honest limitations of the above, is in SECURITY.md.

Release verification

TAG=v0.3.4
gh release download "$TAG" --pattern "checksums*" -R NICE-DEV226/nice-Scan
sha256sum --check nice_scan_*_checksums.txt --ignore-missing
gpg --verify nice_scan_*_checksums.txt.sig nice_scan_*_checksums.txt

For a hardcoded chain of trust, the most verifiable option is always to build from the tag you audit:

git clone --branch v0.3.4 --depth 1 https://github.com/NICE-DEV226/nice-Scan.git
cd nice-Scan && go build -o nice_scan ./cmd/nice_scan

Development

make build            # build the CLI
make test             # run the test suite
make run ARGS="hack example.com --timeout 10s"
make build-all        # cross-compile (linux/windows/darwin, amd64/arm64)
make lint             # golangci-lint (gofmt, staticcheck, …)
make vet              # go vet
make govulncheck      # known-vulnerability scan of dependencies
make snapshot         # local release snapshot (goreleaser)

CI (GitHub Actions) enforces, on every push and pull request: golangci-lint → build → go test -race -count=1 → govulncheck. A change is not "done" until CI is green. Contributor details and conventions are in CONTRIBUTING.md.

Architecture

cmd/nice_scan/     CLI entry point — Cobra commands, flag wiring, rendering choice
internal/
  hacker/          Decision engine: planner, forward-chaining, knowledge base, actions
  engine/          Analysis modules: SQLi, XSS, CORS, headers, TLS, tokens, auth, creds
  recon/           Evidence service: scoped client + analyzer roster -> graded findings,
                   no rendering (the CLI, the TUI and any scripted caller drive this)
  exploit/         Exploitation modules: login, IDOR, privesc, token, session
  detect/          Shared evidence primitives: canaries and classified reflection
  fingerprint/     Technology fingerprinting (165 signatures, stack classifier)
  transport/       HTTP client: pooling, retries, HTTP/2, session/redirect hops, credentials
  shell/           Interactive REPL (history, clipboard copy, consent toggle)
  tui/             Live terminal dashboard (BubbleTea)
  output/          Renderers: terminal, JSON, SARIF, HTML
  types/           Shared types, sanitization, secret masking
  update/          Self-update with checksum verification and rollback
scripts/           Install scripts (install.sh, install.ps1)
docs/              Landing page and architecture documentation

Documentation

Responsible use

nice_scan is intended exclusively for authorized security testing of systems you own or have explicit written permission to test. Unauthorized scanning or exploitation may be illegal in your jurisdiction. The authors accept no liability for misuse or damage. State-changing capabilities are consent-gated for this reason, but the gate is a safeguard, not a substitute for authorization — you are responsible for staying within scope.

To report a vulnerability in nice_scan itself, follow SECURITY.md; do not open a public issue for an unfixed security problem.

License

Distributed under the MIT License. See LICENSE for the full text.


Built with Go · Cobra · BubbleTea · Lipgloss

About

Evidence-first web security scanner — proof or nothing. DAST with provenance grades, two-session BOLA, OpenAPI grey-box, JS surface discovery, SARIF CI gating. MIT, single Go binary, air-gap ready.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages