From 64790bfb34dc3ff7719b188b460df901854a1046 Mon Sep 17 00:00:00 2001 From: Vlastislav Svatek Date: Tue, 26 May 2026 11:45:07 +0200 Subject: [PATCH] add .env and gitignore --- .env.example | 16 +++++ .gitignore | 25 ++++++++ README.md | 149 +++++++++++++++++++++++++++++++-------------- docker-compose.yml | 9 +-- 4 files changed, 146 insertions(+), 53 deletions(-) create mode 100644 .env.example create mode 100644 .gitignore diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..7169ff5 --- /dev/null +++ b/.env.example @@ -0,0 +1,16 @@ +# NetBox connection +NETBOX_URL=https://netbox.example.com/ +NETBOX_TOKEN=your_token_here +SSL_VERIFY=false + +# Scan configuration +# SCAN_SOURCE: env | netbox | mixed +SCAN_SOURCE=env +NETWORKS=192.168.85.0/24,192.168.86.0/24 + +# Filter NetBox prefixes by status when SCAN_SOURCE=netbox or mixed +# Options: active, reserved, deprecated, container (leave empty for all) +NETBOX_PREFIX_STATUS=active + +# NetBox tenant name to assign to discovered IPs +TENANT=Your Tenant Name diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c574aa4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,25 @@ +# Environment variables +.env +.env.* +!.env.example + +# Python +__pycache__/ +*.py[cod] +*.egg-info/ +dist/ +build/ +*.egg +.venv/ +venv/ +env/ + +# Output files +output/ + +# Docker +*.log + +# IDE +.vscode/ +.idea/ diff --git a/README.md b/README.md index 6093ab0..651a1c8 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,130 @@ -# Netbox Scanner +# NetBox Scanner -This repository includes a simple Dockerized network scanner and a NetBox importer. +A Dockerized network scanner that discovers hosts with Nmap and imports them into [NetBox](https://netbox.dev/) as IP address records. -## Services +## How it works -- `scanner`: runs `scan.py` and saves scan results to `output/network.txt` -- `netbox-importer`: runs `ipscan-v2.py` and imports scan results into NetBox +1. **Scanner** (`scan.py`) — performs an Nmap sweep of configured networks and writes results to `output/network.txt`. +2. **NetBox Importer** (`ipscan-v2.py`) — scans networks directly with Nmap, resolves hostnames via DNS, then creates or updates IP address records in NetBox. IPs not found during the scan are marked as `offline`. -## Files +Networks to scan can come from the environment variable `NETWORKS`, from NetBox IPAM prefixes, or both — controlled by `SCAN_SOURCE`. -- `scan.py`: performs Nmap scans for configured networks and writes `network.txt` -- `ipscan-v2.py`: imports scan results into NetBox using environment variables -- `docker-compose.yml`: defines `scanner` and `netbox-importer` services -- `Dockerfile`: installs Python and Nmap and copies both scripts into the container +## Requirements -## Usage +- Docker and Docker Compose -### Build and run the scanner +## Setup + +1. Copy the example environment file and fill in your values: + +```bash +cp .env.example .env +``` + +2. Edit `.env`: + +```env +NETBOX_URL=https://netbox.example.com/ +NETBOX_TOKEN=your_token_here +SSL_VERIFY=false + +SCAN_SOURCE=env +NETWORKS=192.168.1.0/24,192.168.2.0/24 + +NETBOX_PREFIX_STATUS=active +TENANT=Your Tenant Name +``` + +3. Build the image: ```bash docker compose build -docker compose up scanner ``` -The scan output is written to: - -```bash -./output/network.txt -``` +## Usage ### Run the NetBox importer +Scans all configured networks and imports results into NetBox: + ```bash docker compose up netbox-importer ``` -## Configuration +### Run the standalone scanner -### Scanner service +Scans networks and writes results to `./output/network.txt`: -- `OUTPUT_PATH`: path to save results inside container (default: `/app/output/network.txt`) -- `SCAN_NETWORKS`: comma-separated CIDR networks to scan (default set in `scan.py`) - -### NetBox importer service - -- `NETBOX_URL`: NetBox API URL -- `NETBOX_TOKEN`: NetBox API token -- `NETWORKS`: comma-separated networks to scan -- `TENANT`: NetBox tenant name -- `SSL_VERIFY`: whether to verify SSL (`false`, `0`, `no` disable verification) -- `SCAN_SOURCE`: `env`, `netbox`, or `mixed` (use NetBox prefix data for scan networks) -- `NETBOX_PREFIX_STATUS`: optional prefix status filter for NetBox prefixes (for example `active`) - -## Output format - -The generated `network.txt` file includes scan results in this format: - -```text -# network.txt generated on 2026-05-20T00:00:00Z -# host status open_ports -192.168.85.1 up 22 80 -192.168.85.2 down +```bash +docker compose up scanner ``` -## Notes - -- Ensure `nmap` is installed in the container via the provided `Dockerfile`. -- If you want to run both services together, use: +### Run both services ```bash docker compose up scanner netbox-importer ``` + +## Configuration + +All configuration is done via environment variables. Copy `.env.example` to `.env` and set the values there. + +### NetBox importer (`ipscan-v2.py`) + +| Variable | Default | Description | +|---|---|---| +| `NETBOX_URL` | — | NetBox instance URL | +| `NETBOX_TOKEN` | — | NetBox API token | +| `SSL_VERIFY` | `false` | Set to `true` to verify SSL certificates | +| `SCAN_SOURCE` | `env` | Where to get networks: `env`, `netbox`, or `mixed` | +| `NETWORKS` | — | Comma-separated CIDR networks (used when `SCAN_SOURCE=env` or `mixed`) | +| `NETBOX_PREFIX_STATUS` | _(all)_ | Filter NetBox prefixes by status, e.g. `active`, `reserved` (used when `SCAN_SOURCE=netbox` or `mixed`) | +| `TENANT` | — | NetBox tenant name to assign to imported IPs | + +**`SCAN_SOURCE` values:** + +- `env` — scan only networks from `NETWORKS` +- `netbox` — scan only prefixes fetched from NetBox IPAM +- `mixed` — combine both sources + +### Scanner service (`scan.py`) + +| Variable | Default | Description | +|---|---|---| +| `OUTPUT_PATH` | `/app/output/network.txt` | Path inside the container to write results | + +## Scan behaviour + +- Port range scanned: `1–32768` (TCP) +- Timing template: `-T4` (aggressive) +- Per-host timeout: 2 minutes +- Up to 5 networks and 5 hosts are processed in parallel (thread pool) +- Hosts that were previously in NetBox but not found in the current scan are set to status `offline` + +## Output format (`network.txt`) + +```text +192.168.1.1 up 22 80 443 +192.168.1.2 down +``` + +## Project structure + +``` +. +├── ipscan-v2.py # NetBox importer script +├── scan.py # Standalone Nmap scanner +├── Dockerfile # Python 3.14-slim + Nmap + Tini +├── docker-compose.yml # Defines scanner and netbox-importer services +├── requirements.txt # python-nmap, pynetbox, requests +├── .env # Local environment config (gitignored) +└── .env.example # Template — safe to commit +``` + +## Dependencies + +| Package | Version | +|---|---| +| `python-nmap` | 0.7.1 | +| `pynetbox` | 7.4.1 | +| `requests` | 2.32.3 | diff --git a/docker-compose.yml b/docker-compose.yml index 42c424a..1726748 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -15,10 +15,5 @@ services: container_name: netbox_importer tty: true command: python ipscan-v2.py - environment: - - NETBOX_URL=https://netbox.xxxxx.xx/ - - NETBOX_TOKEN=xxxxx - - NETWORKS=192.168.85.0/24,192.168.86.0/24 - - TENANT=Xxxxx Praha - - SSL_VERIFY=false - - SCAN_SOURCE=env + env_file: + - .env