// SIGN IN TO CONTINUE
Single sign-on required
The documentation is available to signed-in users. Sign in with any provider — it's free.
// YOUR OPERATING SYSTEM
Detected automatically — switch tabs any time and the instructions below follow.
1 · Install Docker (one time)
// the only prerequisiteGet Docker Desktop, start it, and wait until it reports that it's running. NewScan does not need a Docker Hub account and never pulls an image.
On Apple silicon and Intel alike, the standard Docker Desktop build is what you want. On Windows, Docker Desktop uses the WSL 2 backend — accept its prompt to install WSL if you don't have it yet, then reboot when asked. On Linux you can use Docker Desktop or plain Docker Engine plus the Compose plugin (docker compose version should print v2 or newer).
CHECK IT
If both print a version, you're ready. If docker isn't found, Docker Desktop isn't running yet.
2 · Download and start NewScan
// one download, image includedGrab the download from your account downloads. macOS gets a disk image: open it and drag NewScan into Applications.Unzip it anywhere you like — keep the files together, the launcher expects its siblings.Unzip it anywhere you like — keep the files together, the launcher expects its siblings. Then start it:
// START IT
Open the .dmg, drag NewScan onto the Applications folder beside it, then open it from Applications — the app is the whole launcher.
It's a signed, notarized macOS app: it opens a Terminal window, loads the bundled image on first run, starts the host helper for Wi-Fi/network modes, and opens the console in your browser. There is deliberately no loose shell script to click — Gatekeeper flags those. The drag into Applications matters: an app left in your download folder runs from a read-only system mount that can't reach its own files.
Double-click NewScan.exe.
It loads the bundled image on first run, starts the host helper for Wi-Fi/network modes, and opens the console. It's code-signed — Windows names the publisher as New Normal Security. It's a small signed launcher around start-win.cmd: it clears the "came from the internet" mark on the folder (the old right-click → Unblock step) and runs that script, which stays plain text you can read in Notepad first. A .cmd can't carry a signature at all, which is why the .exe exists.
Make it executable once, then run it:
First run takes a moment while the image loads, then the console opens at http://localhost:9700.
// WINDOWS: IF DEFENDER OBJECTS
The launcher and the host helper are both code-signed as New Normal Security, so you should see the publisher named, not "Unknown Publisher". What a signature can't buy instantly is reputation — Windows treats a newly issued certificate with suspicion for a while. Two things it may still do, and only the last step needs admin.
1 · "Windows protected your PC" / "prevented an unrecognized app from starting"
That's SmartScreen judging reputation, not the signature — a newly issued certificate has none yet, and it builds up as a release spreads. The tell that the signature is fine: the dialog names a Publisher. Windows lists our certificate's address parts first, so it reads US, Idaho, Meridian, New Normal Security. Check that, then click More info → Run anyway. An unsigned file is the one that says "Unknown Publisher". Prefer to read before you run? NewScan.exe only unblocks the folder and runs start-win.cmd, which is plain text sitting right beside it.
2 · If Wi-Fi / Network / Segmentation modes are missing, Defender ate the host helper
newscan-hosthelper-win.exe opens a local listener, which Defender can flag on a brand-new signature. The tell: those scan modes are hidden in the console and the .exe has vanished from the folder. To restore it:
- Windows Security → Virus & threat protection → Protection history → the NewScan item → Actions → Allow on device.
- Put the file back: re-extract newscan-hosthelper-win.exe from the zip into the NewScan folder.
- Run NewScan.exe again — Wi-Fi, Network and Segmentation should now be in the scan-mode list.
- To stop it recurring on every update, exclude that one folder (admin PowerShell):
On a work-managed machine, Tamper Protection or policy can grey out both "Allow on device" and the exclusion — your IT admin has to permit it. If security review wants to read the helper before you allow it: it only runs read-only netsh wlan show networks / show profiles and lists your network interfaces, and every request must carry a one-time token the launcher generates locally.
// PREFER TO DRIVE DOCKER YOURSELF?
Same result, minus the launcher. Note that Wi-Fi, network and segmentation modes stay hidden this way — they need the native host helper the launcher starts (see below).
3 · Optional: turn on the AI layer
// bring your own key · free without itNewScan runs fully deterministic with no key at all — the quick and baseline profiles are the algorithmic floor. Add one provider key to unlock the optional AI augmentation phase (full / safe).
The simplest route is the console's own Settings panel — paste the key there and it applies immediately, no restart, no file editing. Keys stay on your machine.
OR VIA THE ENV FILE
Edit ~/.newscan/.env (created on first run), then open NewScan again. Copy .env.example to .env in the unzipped folder, add the key, and run NewScan.exe again. Copy .env.example to .env in the unzipped folder, add the key, and run ./start-lin.sh again.
4 · Wi-Fi & local-network scans
// runs on the host, not in the containerWi-Fi, network and segmentation modes have to touch your real network interfaces, so they run through a small native host helper instead of inside the container. The launcher starts it for you — there is nothing to install.
On macOS, approve the Location permission prompt the first time you run a Wi-Fi scan — the OS requires it for SSID scanning. Nothing is sent anywhere; it's the only way to read nearby networks. On Windows the helper reads the adapters through the standard Wi-Fi service; no extra permission prompt is expected. On Linux the helper needs access to the wireless interface — run the launcher as a user with the usual network privileges (or with sudo) if a Wi-Fi scan reports no adapters.
If you started the raw image without the launcher, these modes are hidden by design — no helper, no false promises.
5 · Ports, updating, stopping, removing
// day-two operationsPORTS
9700 is the console, HTTP API and MCP server; 9701 is the optional traffic-capture proxy. If either is taken the launcher picks the next free port and remembers it in .env (NEWSCAN_PORT / NEWSCAN_PROXY_PORT — set those to pin your own).
UPDATING
Download the new version and start it the same way (just open the new NewScan app)(run the new NewScan.exe)(run the new ./start-lin.sh). It loads the new bundled image and replaces the running container in place. Scan history, settings and your license survive the upgrade — they live in named Docker volumes, not in the folder.
STOPPING
Quit from the app window, or run docker compose -p newscan down. Double-click Stop NewScan.exe, or run docker compose -p newscan down. Run ./stop-lin.sh, or docker compose -p newscan down. Your scan history is kept.
REMOVING IT COMPLETELY
Then delete NewScan.app from Applicationsthe unzipped folderthe unzipped folder. Removing the volumes also deletes scan history and your activated license state.
6 · From source, and in CI
// the same scanner, no launcherRUN FROM SOURCE
Chromium powers SPA discovery and browser-driven login. Everything else is pure Python.
ONE-SHOT HEADLESS SCAN
Exit code 0 clean · 1 a finding at or above the threshold · 2 the scan couldn't run. More in Run it in CI/CD.
Stuck on a step? Open a support ticket →