Garoshi/netbox-scanner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add .env and gitignore

Browse Source
This commit is contained in:
Vlastislav Svatek
2026-05-26 11:45:07 +02:00
parent 5c450c5ab1
commit 64790bfb34
4 changed files with 146 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
.env.example Normal file
View File

@@ -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

25
.gitignore vendored Normal file
View File

@@ -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/

149
README.md
View File

@@ -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 |

9
docker-compose.yml
View File

@@ -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