netpulse 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- netpulse-0.1.0/LICENSE +21 -0
- netpulse-0.1.0/PKG-INFO +271 -0
- netpulse-0.1.0/README.md +256 -0
- netpulse-0.1.0/pyproject.toml +35 -0
- netpulse-0.1.0/rust/Cargo.lock +507 -0
- netpulse-0.1.0/rust/Cargo.toml +16 -0
- netpulse-0.1.0/rust/LICENSE +21 -0
- netpulse-0.1.0/rust/src/lib.rs +367 -0
- netpulse-0.1.0/src/netpulse_rust/__init__.py +1 -0
netpulse-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Bonheur Ndeze
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
netpulse-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: netpulse
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Requires-Dist: pydantic>=2.0.0
|
|
5
|
+
Requires-Dist: typer>=0.9.0
|
|
6
|
+
Requires-Dist: rich>=13.0.0
|
|
7
|
+
Requires-Dist: fastapi>=0.100.0
|
|
8
|
+
Requires-Dist: uvicorn>=0.22.0
|
|
9
|
+
Requires-Dist: asyncssh>=2.14.0
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Summary: High-performance network discovery and subnet analysis suite with native Rust speed.
|
|
12
|
+
Requires-Python: >=3.14
|
|
13
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
14
|
+
|
|
15
|
+
# โก NetPulse
|
|
16
|
+
|
|
17
|
+
[](https://www.python.org/)
|
|
18
|
+
[](https://www.rust-lang.org/)
|
|
19
|
+
[](https://fastapi.tiangolo.com/)
|
|
20
|
+
[](LICENSE)
|
|
21
|
+
[](https://github.com/bonheurNE07/netpulse/actions/workflows/release.yml)
|
|
22
|
+
|
|
23
|
+
**NetPulse** is a high-performance, modern network discovery and analysis suite. It marries the speed and safety of low-level **Rust raw-socket packet crafting** with the developer ergonomics of **Python, FastAPI, and Typer**.
|
|
24
|
+
|
|
25
|
+
Designed as a modern monorepo, NetPulse is optimized for rapid Layer 2 (ARP) and Layer 3 (ICMP) network sweeps.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## ๐ System Architecture
|
|
30
|
+
|
|
31
|
+
NetPulse is structured as a modular monorepo that separates high-speed systems execution (Rust) from orchestration, validation, and delivery interfaces (CLI, REST API).
|
|
32
|
+
|
|
33
|
+
```mermaid
|
|
34
|
+
graph TD
|
|
35
|
+
A[Client Interfaces] --> B[CLI: apps/cli]
|
|
36
|
+
A --> C[REST API: apps/api]
|
|
37
|
+
B --> D[Core Service: packages/core]
|
|
38
|
+
C --> D
|
|
39
|
+
D --> E[Engine Interface: packages/engine]
|
|
40
|
+
E --> F[Rust Core Extension: rust/src/lib.rs]
|
|
41
|
+
F -->|Raw L2 ARP Frames| G[Network Interface Card]
|
|
42
|
+
F -->|Raw L3 ICMP Sweeps| G
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## ๐ Monorepo Layout
|
|
48
|
+
|
|
49
|
+
| Component Path | Language | Description |
|
|
50
|
+
| :--- | :--- | :--- |
|
|
51
|
+
| [**`rust/`**](file:///home/bonheur/netpulse/rust) | Rust | High-speed native core utilizing raw sockets (`pnet`, `socket2`) for ARP framing and ICMP sweeps. |
|
|
52
|
+
| [**`packages/core/`**](file:///home/bonheur/netpulse/packages/core) | Python | Central orchestration layer (`netpulse_core`). Defines domain Pydantic V2 models, handles service coordination, and powers the Subnetting & VLSM calculation engine. |
|
|
53
|
+
| [**`packages/engine/`**](file:///home/bonheur/netpulse/packages/engine) | Python | Loader package (`netpulse_engine`) exposing compiled Rust bindings to Python, featuring a zero-privilege mock fallback. |
|
|
54
|
+
| [**`apps/cli/`**](file:///home/bonheur/netpulse/apps/cli) | Python | Premium CLI tool (`netpulse_cli`) powered by `Typer` and `Rich` for beautiful terminal data representation. |
|
|
55
|
+
| [**`apps/api/`**](file:///home/bonheur/netpulse/apps/api) | Python | Production-ready FastAPI service (`netpulse_api`) featuring custom rate-limiters, security headers, and CORS restrictions. |
|
|
56
|
+
| [**`tests/`**](file:///home/bonheur/netpulse/tests) | Python | Complete automated test suite verifying models, mock engine interfaces, CLI, and API layers. |
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## ๐ Security & Elevated Privileges
|
|
61
|
+
|
|
62
|
+
Because L2 ARP (ethernet frames) and L3 ICMP (ping) sweeps open and read from raw network sockets, they require systems-level privileges under Linux.
|
|
63
|
+
|
|
64
|
+
### ๐ก๏ธ Local Testing (Mock Mode)
|
|
65
|
+
To build and test NetPulse locally without needing root privileges, you can activate **Forced Mock Mode** by exporting the environment variable:
|
|
66
|
+
```bash
|
|
67
|
+
export NETPULSE_MOCK=1
|
|
68
|
+
```
|
|
69
|
+
In mock mode, the Python engine will bypass the Rust raw socket layer and return simulated subnets instantly, preserving full layout, validation, and API testing capabilities.
|
|
70
|
+
|
|
71
|
+
### โก Running in Native Production Mode
|
|
72
|
+
When executing real scans on a network interface card, you must provide the python interpreter with standard Linux network capabilities or run with superuser rights:
|
|
73
|
+
|
|
74
|
+
* **Option A (Recommended): Grant capabilities to the virtualenv Python binary**
|
|
75
|
+
```bash
|
|
76
|
+
sudo setcap cap_net_raw,cap_net_admin+eip $(readlink -f .venv/bin/python)
|
|
77
|
+
```
|
|
78
|
+
* **Option B: Execute via superuser (`sudo`)**
|
|
79
|
+
```bash
|
|
80
|
+
sudo .venv/bin/python apps/cli/netpulse_cli/main.py discover 192.168.1.0/24
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## ๐ Installation & Build
|
|
86
|
+
|
|
87
|
+
NetPulse uses [`uv`](https://github.com/astral-sh/uv) to manage its dependencies, and compiles its Rust engine inline using [`maturin`](https://github.com/PyO3/maturin).
|
|
88
|
+
|
|
89
|
+
### Prerequisites
|
|
90
|
+
Ensure you have Rust, cargo, and python installed on your system.
|
|
91
|
+
|
|
92
|
+
### Steps
|
|
93
|
+
1. **Clone the workspace** and navigate to the project directory:
|
|
94
|
+
```bash
|
|
95
|
+
cd netpulse
|
|
96
|
+
```
|
|
97
|
+
2. **Sync workspace dependencies** using `uv`:
|
|
98
|
+
```bash
|
|
99
|
+
uv sync
|
|
100
|
+
```
|
|
101
|
+
3. **Compile and register the Rust engine** inside the virtual environment:
|
|
102
|
+
```bash
|
|
103
|
+
cd rust
|
|
104
|
+
../.venv/bin/maturin develop --release
|
|
105
|
+
cd ..
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## ๐ฅ๏ธ Command Line Interface (CLI)
|
|
111
|
+
|
|
112
|
+
The CLI offers stunning console aesthetics with dynamic loading states, table outputs, and detailed error instructions.
|
|
113
|
+
|
|
114
|
+
### Subcommands
|
|
115
|
+
* **`version`**: Shows package and CLI version details.
|
|
116
|
+
* **`discover [target]`**: Sweeps the target CIDR network and automatically stores the result in history.
|
|
117
|
+
* **`discover-history [network]`**: Queries all past discovery scan summaries from local SQLite storage.
|
|
118
|
+
* **`discover-drift [target]`**: Sweeps the network target and instantly computes status drift against baseline history.
|
|
119
|
+
* **`discover-compare [old_scan_uuid] [new_scan_uuid]`**: Compares two specific past sweeps in database history.
|
|
120
|
+
* **`subnet info [ip_or_cidr]`**: Calculates network boundaries and displays bitwise binary alignments.
|
|
121
|
+
* **`subnet split [parent_network]`**: Partitions a parent CIDR into equal-sized subnets (FLSM) by count (`--subnets`) or host capacity (`--hosts`).
|
|
122
|
+
* **`subnet vlsm [parent_network]`**: Calculates optimal subnets using Variable-Length Subnet Masking (VLSM) for varying host size requirements.
|
|
123
|
+
* **`subnet discover [ip]`**: Finds which containing CIDR subnet block from a candidate list contains the given IP address.
|
|
124
|
+
|
|
125
|
+
### Execution Examples
|
|
126
|
+
```bash
|
|
127
|
+
# Standard interactive table sweep (requires root or setcap permissions)
|
|
128
|
+
sudo .venv/bin/python apps/cli/netpulse_cli/main.py discover 172.19.57.0/24
|
|
129
|
+
|
|
130
|
+
# Output results directly in formatted JSON
|
|
131
|
+
NETPULSE_MOCK=1 .venv/bin/python apps/cli/netpulse_cli/main.py discover 172.19.57.0/24 --format json
|
|
132
|
+
|
|
133
|
+
# Subnet bitwise alignment calculator
|
|
134
|
+
.venv/bin/python apps/cli/netpulse_cli/main.py subnet info 192.168.1.50/24
|
|
135
|
+
|
|
136
|
+
# Perform VLSM allocation for varying departmental size requirements
|
|
137
|
+
.venv/bin/python apps/cli/netpulse_cli/main.py subnet vlsm 192.168.1.0/24 --req "HR=120,Dev=50,Sales=20,Links=2"
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## ๐ REST API Service
|
|
143
|
+
|
|
144
|
+
The REST API is a secure, production-grade FastAPI web service.
|
|
145
|
+
|
|
146
|
+
### API Security Features
|
|
147
|
+
1. **Strict Bind Address**: Exclusively listens on localhost (`127.0.0.1:8000`) for development, avoiding open exposures (`0.0.0.0`).
|
|
148
|
+
2. **Sliding Window Rate Limiter**: Limits clients to **5 scans per minute per IP**, returning structured `429 Too Many Requests` responses with `retry_after_seconds` retry bounds.
|
|
149
|
+
3. **Security Headers**: Emits strict headers on every response:
|
|
150
|
+
* `X-Content-Type-Options: nosniff`
|
|
151
|
+
* `X-Frame-Options: DENY`
|
|
152
|
+
* `Content-Security-Policy: default-src 'self';`
|
|
153
|
+
4. **CORS Restrictions**: Rejects wildcards (`*`) and explicitly boundaries access to `localhost:3000` developers.
|
|
154
|
+
5. **Structured Error Translation**: Safe handling of raw socket `PermissionError` codes, translating them into helpful instructions.
|
|
155
|
+
|
|
156
|
+
### Start the REST Server
|
|
157
|
+
```bash
|
|
158
|
+
# Run in Mock Mode (Unprivileged)
|
|
159
|
+
PYTHONPATH=apps/api NETPULSE_MOCK=1 .venv/bin/python -m uvicorn netpulse_api.main:app --host 127.0.0.1 --port 8000
|
|
160
|
+
|
|
161
|
+
# Run in Production Mode (Requires raw socket capabilities)
|
|
162
|
+
sudo PYTHONPATH=apps/api .venv/bin/python -m uvicorn netpulse_api.main:app --host 127.0.0.1 --port 8000
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Endpoint Reference
|
|
166
|
+
|
|
167
|
+
#### `GET /health`
|
|
168
|
+
Validates server reachability and responds with compliancy metadata.
|
|
169
|
+
* **Response (200)**:
|
|
170
|
+
```json
|
|
171
|
+
{
|
|
172
|
+
"status": "healthy",
|
|
173
|
+
"service": "netpulse-api",
|
|
174
|
+
"timestamp": 1779482308.33
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
#### `POST /api/v1/discover`
|
|
179
|
+
Orchestrates a discovery scan.
|
|
180
|
+
* **Request Payload**:
|
|
181
|
+
```json
|
|
182
|
+
{
|
|
183
|
+
"target_network": "172.19.57.0/24",
|
|
184
|
+
"methods": ["icmp"],
|
|
185
|
+
"timeout_ms": 1000
|
|
186
|
+
}
|
|
187
|
+
```
|
|
188
|
+
* **Response (200)**:
|
|
189
|
+
```json
|
|
190
|
+
{
|
|
191
|
+
"id": "7b86da45-ad65-4b55-b200-92a41a71a998",
|
|
192
|
+
"network": "172.19.57.0/24",
|
|
193
|
+
"methods": ["icmp"],
|
|
194
|
+
"status": "completed",
|
|
195
|
+
"errors": [],
|
|
196
|
+
"devices": [
|
|
197
|
+
{
|
|
198
|
+
"id": "e38d70be-71fa-4677-962a-62bbb3685394",
|
|
199
|
+
"ip": "172.19.57.1",
|
|
200
|
+
"mac": null,
|
|
201
|
+
"hostname": null,
|
|
202
|
+
"vendor": null,
|
|
203
|
+
"status": "up",
|
|
204
|
+
"rtt_ms": 0.35
|
|
205
|
+
}
|
|
206
|
+
],
|
|
207
|
+
"started_at": "2026-05-22T20:47:32.256Z",
|
|
208
|
+
"finished_at": "2026-05-22T20:47:32.257Z",
|
|
209
|
+
"stats": {
|
|
210
|
+
"scanned": 256,
|
|
211
|
+
"responsive": 1
|
|
212
|
+
},
|
|
213
|
+
"metadata": {}
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
#### `POST /api/v1/subnet/info`
|
|
218
|
+
Acts as a subnet calculator. Computes detailed boundary configurations.
|
|
219
|
+
* **Request Payload**:
|
|
220
|
+
```json
|
|
221
|
+
{
|
|
222
|
+
"ip": "192.168.1.50",
|
|
223
|
+
"mask_or_prefix": "24"
|
|
224
|
+
}
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
#### `POST /api/v1/subnet/split`
|
|
228
|
+
Partitions a parent CIDR into equal-sized subnets (FLSM).
|
|
229
|
+
* **Request Payload**:
|
|
230
|
+
```json
|
|
231
|
+
{
|
|
232
|
+
"parent_network": "192.168.1.0/24",
|
|
233
|
+
"subnets_count": 4
|
|
234
|
+
}
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
#### `POST /api/v1/subnet/vlsm`
|
|
238
|
+
Calculates optimal Variable-Length Subnet Masking (VLSM) allocations.
|
|
239
|
+
* **Request Payload**:
|
|
240
|
+
```json
|
|
241
|
+
{
|
|
242
|
+
"parent_network": "192.168.1.0/24",
|
|
243
|
+
"requirements": [
|
|
244
|
+
{"name": "HR", "hosts": 120},
|
|
245
|
+
{"name": "Dev", "hosts": 50}
|
|
246
|
+
]
|
|
247
|
+
}
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
#### `POST /api/v1/subnet/discover`
|
|
251
|
+
Matches a target IP against candidate subnets to locate its container.
|
|
252
|
+
* **Request Payload**:
|
|
253
|
+
```json
|
|
254
|
+
{
|
|
255
|
+
"ip": "192.168.1.45",
|
|
256
|
+
"subnets": ["192.168.1.0/26", "192.168.1.64/26"]
|
|
257
|
+
}
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## ๐งช Running Automated Tests
|
|
263
|
+
|
|
264
|
+
NetPulse comes with **69 automated unit and integration tests** built on top of `pytest` and `httpx`.
|
|
265
|
+
|
|
266
|
+
Tests run securely inside the local sandbox using mock overrides without needing root/sudo permissions:
|
|
267
|
+
|
|
268
|
+
```bash
|
|
269
|
+
PYTHONPATH=apps/api:apps/cli:packages/core:packages/engine NETPULSE_MOCK=1 .venv/bin/pytest tests/ -v
|
|
270
|
+
```
|
|
271
|
+
|
netpulse-0.1.0/README.md
ADDED
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
# โก NetPulse
|
|
2
|
+
|
|
3
|
+
[](https://www.python.org/)
|
|
4
|
+
[](https://www.rust-lang.org/)
|
|
5
|
+
[](https://fastapi.tiangolo.com/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](https://github.com/bonheurNE07/netpulse/actions/workflows/release.yml)
|
|
8
|
+
|
|
9
|
+
**NetPulse** is a high-performance, modern network discovery and analysis suite. It marries the speed and safety of low-level **Rust raw-socket packet crafting** with the developer ergonomics of **Python, FastAPI, and Typer**.
|
|
10
|
+
|
|
11
|
+
Designed as a modern monorepo, NetPulse is optimized for rapid Layer 2 (ARP) and Layer 3 (ICMP) network sweeps.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## ๐ System Architecture
|
|
16
|
+
|
|
17
|
+
NetPulse is structured as a modular monorepo that separates high-speed systems execution (Rust) from orchestration, validation, and delivery interfaces (CLI, REST API).
|
|
18
|
+
|
|
19
|
+
```mermaid
|
|
20
|
+
graph TD
|
|
21
|
+
A[Client Interfaces] --> B[CLI: apps/cli]
|
|
22
|
+
A --> C[REST API: apps/api]
|
|
23
|
+
B --> D[Core Service: packages/core]
|
|
24
|
+
C --> D
|
|
25
|
+
D --> E[Engine Interface: packages/engine]
|
|
26
|
+
E --> F[Rust Core Extension: rust/src/lib.rs]
|
|
27
|
+
F -->|Raw L2 ARP Frames| G[Network Interface Card]
|
|
28
|
+
F -->|Raw L3 ICMP Sweeps| G
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## ๐ Monorepo Layout
|
|
34
|
+
|
|
35
|
+
| Component Path | Language | Description |
|
|
36
|
+
| :--- | :--- | :--- |
|
|
37
|
+
| [**`rust/`**](file:///home/bonheur/netpulse/rust) | Rust | High-speed native core utilizing raw sockets (`pnet`, `socket2`) for ARP framing and ICMP sweeps. |
|
|
38
|
+
| [**`packages/core/`**](file:///home/bonheur/netpulse/packages/core) | Python | Central orchestration layer (`netpulse_core`). Defines domain Pydantic V2 models, handles service coordination, and powers the Subnetting & VLSM calculation engine. |
|
|
39
|
+
| [**`packages/engine/`**](file:///home/bonheur/netpulse/packages/engine) | Python | Loader package (`netpulse_engine`) exposing compiled Rust bindings to Python, featuring a zero-privilege mock fallback. |
|
|
40
|
+
| [**`apps/cli/`**](file:///home/bonheur/netpulse/apps/cli) | Python | Premium CLI tool (`netpulse_cli`) powered by `Typer` and `Rich` for beautiful terminal data representation. |
|
|
41
|
+
| [**`apps/api/`**](file:///home/bonheur/netpulse/apps/api) | Python | Production-ready FastAPI service (`netpulse_api`) featuring custom rate-limiters, security headers, and CORS restrictions. |
|
|
42
|
+
| [**`tests/`**](file:///home/bonheur/netpulse/tests) | Python | Complete automated test suite verifying models, mock engine interfaces, CLI, and API layers. |
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## ๐ Security & Elevated Privileges
|
|
47
|
+
|
|
48
|
+
Because L2 ARP (ethernet frames) and L3 ICMP (ping) sweeps open and read from raw network sockets, they require systems-level privileges under Linux.
|
|
49
|
+
|
|
50
|
+
### ๐ก๏ธ Local Testing (Mock Mode)
|
|
51
|
+
To build and test NetPulse locally without needing root privileges, you can activate **Forced Mock Mode** by exporting the environment variable:
|
|
52
|
+
```bash
|
|
53
|
+
export NETPULSE_MOCK=1
|
|
54
|
+
```
|
|
55
|
+
In mock mode, the Python engine will bypass the Rust raw socket layer and return simulated subnets instantly, preserving full layout, validation, and API testing capabilities.
|
|
56
|
+
|
|
57
|
+
### โก Running in Native Production Mode
|
|
58
|
+
When executing real scans on a network interface card, you must provide the python interpreter with standard Linux network capabilities or run with superuser rights:
|
|
59
|
+
|
|
60
|
+
* **Option A (Recommended): Grant capabilities to the virtualenv Python binary**
|
|
61
|
+
```bash
|
|
62
|
+
sudo setcap cap_net_raw,cap_net_admin+eip $(readlink -f .venv/bin/python)
|
|
63
|
+
```
|
|
64
|
+
* **Option B: Execute via superuser (`sudo`)**
|
|
65
|
+
```bash
|
|
66
|
+
sudo .venv/bin/python apps/cli/netpulse_cli/main.py discover 192.168.1.0/24
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## ๐ Installation & Build
|
|
72
|
+
|
|
73
|
+
NetPulse uses [`uv`](https://github.com/astral-sh/uv) to manage its dependencies, and compiles its Rust engine inline using [`maturin`](https://github.com/PyO3/maturin).
|
|
74
|
+
|
|
75
|
+
### Prerequisites
|
|
76
|
+
Ensure you have Rust, cargo, and python installed on your system.
|
|
77
|
+
|
|
78
|
+
### Steps
|
|
79
|
+
1. **Clone the workspace** and navigate to the project directory:
|
|
80
|
+
```bash
|
|
81
|
+
cd netpulse
|
|
82
|
+
```
|
|
83
|
+
2. **Sync workspace dependencies** using `uv`:
|
|
84
|
+
```bash
|
|
85
|
+
uv sync
|
|
86
|
+
```
|
|
87
|
+
3. **Compile and register the Rust engine** inside the virtual environment:
|
|
88
|
+
```bash
|
|
89
|
+
cd rust
|
|
90
|
+
../.venv/bin/maturin develop --release
|
|
91
|
+
cd ..
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## ๐ฅ๏ธ Command Line Interface (CLI)
|
|
97
|
+
|
|
98
|
+
The CLI offers stunning console aesthetics with dynamic loading states, table outputs, and detailed error instructions.
|
|
99
|
+
|
|
100
|
+
### Subcommands
|
|
101
|
+
* **`version`**: Shows package and CLI version details.
|
|
102
|
+
* **`discover [target]`**: Sweeps the target CIDR network and automatically stores the result in history.
|
|
103
|
+
* **`discover-history [network]`**: Queries all past discovery scan summaries from local SQLite storage.
|
|
104
|
+
* **`discover-drift [target]`**: Sweeps the network target and instantly computes status drift against baseline history.
|
|
105
|
+
* **`discover-compare [old_scan_uuid] [new_scan_uuid]`**: Compares two specific past sweeps in database history.
|
|
106
|
+
* **`subnet info [ip_or_cidr]`**: Calculates network boundaries and displays bitwise binary alignments.
|
|
107
|
+
* **`subnet split [parent_network]`**: Partitions a parent CIDR into equal-sized subnets (FLSM) by count (`--subnets`) or host capacity (`--hosts`).
|
|
108
|
+
* **`subnet vlsm [parent_network]`**: Calculates optimal subnets using Variable-Length Subnet Masking (VLSM) for varying host size requirements.
|
|
109
|
+
* **`subnet discover [ip]`**: Finds which containing CIDR subnet block from a candidate list contains the given IP address.
|
|
110
|
+
|
|
111
|
+
### Execution Examples
|
|
112
|
+
```bash
|
|
113
|
+
# Standard interactive table sweep (requires root or setcap permissions)
|
|
114
|
+
sudo .venv/bin/python apps/cli/netpulse_cli/main.py discover 172.19.57.0/24
|
|
115
|
+
|
|
116
|
+
# Output results directly in formatted JSON
|
|
117
|
+
NETPULSE_MOCK=1 .venv/bin/python apps/cli/netpulse_cli/main.py discover 172.19.57.0/24 --format json
|
|
118
|
+
|
|
119
|
+
# Subnet bitwise alignment calculator
|
|
120
|
+
.venv/bin/python apps/cli/netpulse_cli/main.py subnet info 192.168.1.50/24
|
|
121
|
+
|
|
122
|
+
# Perform VLSM allocation for varying departmental size requirements
|
|
123
|
+
.venv/bin/python apps/cli/netpulse_cli/main.py subnet vlsm 192.168.1.0/24 --req "HR=120,Dev=50,Sales=20,Links=2"
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## ๐ REST API Service
|
|
129
|
+
|
|
130
|
+
The REST API is a secure, production-grade FastAPI web service.
|
|
131
|
+
|
|
132
|
+
### API Security Features
|
|
133
|
+
1. **Strict Bind Address**: Exclusively listens on localhost (`127.0.0.1:8000`) for development, avoiding open exposures (`0.0.0.0`).
|
|
134
|
+
2. **Sliding Window Rate Limiter**: Limits clients to **5 scans per minute per IP**, returning structured `429 Too Many Requests` responses with `retry_after_seconds` retry bounds.
|
|
135
|
+
3. **Security Headers**: Emits strict headers on every response:
|
|
136
|
+
* `X-Content-Type-Options: nosniff`
|
|
137
|
+
* `X-Frame-Options: DENY`
|
|
138
|
+
* `Content-Security-Policy: default-src 'self';`
|
|
139
|
+
4. **CORS Restrictions**: Rejects wildcards (`*`) and explicitly boundaries access to `localhost:3000` developers.
|
|
140
|
+
5. **Structured Error Translation**: Safe handling of raw socket `PermissionError` codes, translating them into helpful instructions.
|
|
141
|
+
|
|
142
|
+
### Start the REST Server
|
|
143
|
+
```bash
|
|
144
|
+
# Run in Mock Mode (Unprivileged)
|
|
145
|
+
PYTHONPATH=apps/api NETPULSE_MOCK=1 .venv/bin/python -m uvicorn netpulse_api.main:app --host 127.0.0.1 --port 8000
|
|
146
|
+
|
|
147
|
+
# Run in Production Mode (Requires raw socket capabilities)
|
|
148
|
+
sudo PYTHONPATH=apps/api .venv/bin/python -m uvicorn netpulse_api.main:app --host 127.0.0.1 --port 8000
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Endpoint Reference
|
|
152
|
+
|
|
153
|
+
#### `GET /health`
|
|
154
|
+
Validates server reachability and responds with compliancy metadata.
|
|
155
|
+
* **Response (200)**:
|
|
156
|
+
```json
|
|
157
|
+
{
|
|
158
|
+
"status": "healthy",
|
|
159
|
+
"service": "netpulse-api",
|
|
160
|
+
"timestamp": 1779482308.33
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
#### `POST /api/v1/discover`
|
|
165
|
+
Orchestrates a discovery scan.
|
|
166
|
+
* **Request Payload**:
|
|
167
|
+
```json
|
|
168
|
+
{
|
|
169
|
+
"target_network": "172.19.57.0/24",
|
|
170
|
+
"methods": ["icmp"],
|
|
171
|
+
"timeout_ms": 1000
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
* **Response (200)**:
|
|
175
|
+
```json
|
|
176
|
+
{
|
|
177
|
+
"id": "7b86da45-ad65-4b55-b200-92a41a71a998",
|
|
178
|
+
"network": "172.19.57.0/24",
|
|
179
|
+
"methods": ["icmp"],
|
|
180
|
+
"status": "completed",
|
|
181
|
+
"errors": [],
|
|
182
|
+
"devices": [
|
|
183
|
+
{
|
|
184
|
+
"id": "e38d70be-71fa-4677-962a-62bbb3685394",
|
|
185
|
+
"ip": "172.19.57.1",
|
|
186
|
+
"mac": null,
|
|
187
|
+
"hostname": null,
|
|
188
|
+
"vendor": null,
|
|
189
|
+
"status": "up",
|
|
190
|
+
"rtt_ms": 0.35
|
|
191
|
+
}
|
|
192
|
+
],
|
|
193
|
+
"started_at": "2026-05-22T20:47:32.256Z",
|
|
194
|
+
"finished_at": "2026-05-22T20:47:32.257Z",
|
|
195
|
+
"stats": {
|
|
196
|
+
"scanned": 256,
|
|
197
|
+
"responsive": 1
|
|
198
|
+
},
|
|
199
|
+
"metadata": {}
|
|
200
|
+
}
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
#### `POST /api/v1/subnet/info`
|
|
204
|
+
Acts as a subnet calculator. Computes detailed boundary configurations.
|
|
205
|
+
* **Request Payload**:
|
|
206
|
+
```json
|
|
207
|
+
{
|
|
208
|
+
"ip": "192.168.1.50",
|
|
209
|
+
"mask_or_prefix": "24"
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
#### `POST /api/v1/subnet/split`
|
|
214
|
+
Partitions a parent CIDR into equal-sized subnets (FLSM).
|
|
215
|
+
* **Request Payload**:
|
|
216
|
+
```json
|
|
217
|
+
{
|
|
218
|
+
"parent_network": "192.168.1.0/24",
|
|
219
|
+
"subnets_count": 4
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
#### `POST /api/v1/subnet/vlsm`
|
|
224
|
+
Calculates optimal Variable-Length Subnet Masking (VLSM) allocations.
|
|
225
|
+
* **Request Payload**:
|
|
226
|
+
```json
|
|
227
|
+
{
|
|
228
|
+
"parent_network": "192.168.1.0/24",
|
|
229
|
+
"requirements": [
|
|
230
|
+
{"name": "HR", "hosts": 120},
|
|
231
|
+
{"name": "Dev", "hosts": 50}
|
|
232
|
+
]
|
|
233
|
+
}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
#### `POST /api/v1/subnet/discover`
|
|
237
|
+
Matches a target IP against candidate subnets to locate its container.
|
|
238
|
+
* **Request Payload**:
|
|
239
|
+
```json
|
|
240
|
+
{
|
|
241
|
+
"ip": "192.168.1.45",
|
|
242
|
+
"subnets": ["192.168.1.0/26", "192.168.1.64/26"]
|
|
243
|
+
}
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## ๐งช Running Automated Tests
|
|
249
|
+
|
|
250
|
+
NetPulse comes with **69 automated unit and integration tests** built on top of `pytest` and `httpx`.
|
|
251
|
+
|
|
252
|
+
Tests run securely inside the local sandbox using mock overrides without needing root/sudo permissions:
|
|
253
|
+
|
|
254
|
+
```bash
|
|
255
|
+
PYTHONPATH=apps/api:apps/cli:packages/core:packages/engine NETPULSE_MOCK=1 .venv/bin/pytest tests/ -v
|
|
256
|
+
```
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["maturin>=1.5,<2.0"]
|
|
3
|
+
build-backend = "maturin"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "netpulse"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "High-performance network discovery and subnet analysis suite with native Rust speed."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { file = "LICENSE" }
|
|
11
|
+
requires-python = ">=3.14"
|
|
12
|
+
dependencies = [
|
|
13
|
+
"pydantic>=2.0.0",
|
|
14
|
+
"typer>=0.9.0",
|
|
15
|
+
"rich>=13.0.0",
|
|
16
|
+
"fastapi>=0.100.0",
|
|
17
|
+
"uvicorn>=0.22.0",
|
|
18
|
+
"asyncssh>=2.14.0",
|
|
19
|
+
]
|
|
20
|
+
|
|
21
|
+
[project.scripts]
|
|
22
|
+
netpulse = "netpulse_cli.main:app"
|
|
23
|
+
|
|
24
|
+
[dependency-groups]
|
|
25
|
+
dev = [
|
|
26
|
+
"maturin>=1.13.1",
|
|
27
|
+
"pytest>=7.0.0",
|
|
28
|
+
"pytest-asyncio>=0.21.0",
|
|
29
|
+
"httpx>=0.24.0",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[tool.maturin]
|
|
33
|
+
python-source = "src"
|
|
34
|
+
module-name = "netpulse_rust"
|
|
35
|
+
manifest-path = "rust/Cargo.toml"
|