netcheck-ir 2.0.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.
- netcheck_ir-2.0.0/LICENSE +21 -0
- netcheck_ir-2.0.0/PKG-INFO +231 -0
- netcheck_ir-2.0.0/README.md +205 -0
- netcheck_ir-2.0.0/netcheck/__init__.py +10 -0
- netcheck_ir-2.0.0/netcheck/__main__.py +5 -0
- netcheck_ir-2.0.0/netcheck/ai.py +255 -0
- netcheck_ir-2.0.0/netcheck/checks.py +322 -0
- netcheck_ir-2.0.0/netcheck/cli.py +374 -0
- netcheck_ir-2.0.0/netcheck/config.py +184 -0
- netcheck_ir-2.0.0/netcheck/core.py +466 -0
- netcheck_ir-2.0.0/netcheck/diagnosis.py +133 -0
- netcheck_ir-2.0.0/netcheck/forensics.py +191 -0
- netcheck_ir-2.0.0/netcheck/notify.py +47 -0
- netcheck_ir-2.0.0/netcheck/report.py +115 -0
- netcheck_ir-2.0.0/netcheck/security.py +225 -0
- netcheck_ir-2.0.0/netcheck_ir.egg-info/PKG-INFO +231 -0
- netcheck_ir-2.0.0/netcheck_ir.egg-info/SOURCES.txt +22 -0
- netcheck_ir-2.0.0/netcheck_ir.egg-info/dependency_links.txt +1 -0
- netcheck_ir-2.0.0/netcheck_ir.egg-info/entry_points.txt +2 -0
- netcheck_ir-2.0.0/netcheck_ir.egg-info/requires.txt +5 -0
- netcheck_ir-2.0.0/netcheck_ir.egg-info/top_level.txt +1 -0
- netcheck_ir-2.0.0/pyproject.toml +42 -0
- netcheck_ir-2.0.0/setup.cfg +4 -0
- netcheck_ir-2.0.0/tests/test_netcheck.py +421 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 NetCheck contributors
|
|
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.
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: netcheck-ir
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: Enterprise network triage, security posture, and IR/forensics in one command - with optional AI analysis (Claude / OpenAI / Azure / Ollama).
|
|
5
|
+
Author: NetCheck contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/your-username/netcheck
|
|
8
|
+
Project-URL: Issues, https://github.com/your-username/netcheck/issues
|
|
9
|
+
Keywords: network,diagnostics,troubleshooting,security,incident-response,forensics,dfir,ai,llm,dns,tls,sysadmin,devops,cli
|
|
10
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: System Administrators
|
|
13
|
+
Classifier: Intended Audience :: Information Technology
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Topic :: System :: Networking :: Monitoring
|
|
18
|
+
Classifier: Topic :: System :: Systems Administration
|
|
19
|
+
Classifier: Topic :: Security
|
|
20
|
+
Requires-Python: >=3.8
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Provides-Extra: toml
|
|
24
|
+
Requires-Dist: tomli; python_version < "3.11" and extra == "toml"
|
|
25
|
+
Dynamic: license-file
|
|
26
|
+
|
|
27
|
+
# NetCheck
|
|
28
|
+
|
|
29
|
+
**Enterprise network triage, security posture, and incident-response/forensics in one command — with optional AI analysis.**
|
|
30
|
+
|
|
31
|
+
NetCheck runs the full network-troubleshooting workflow (interface → gateway → internet → DNS → ports → HTTP/captive-portal → TLS → quality, plus optional traceroute/MTU/IPv6), then **diagnoses the root cause** instead of just dumping raw output. On top of that it adds a defensive **security-posture assessment**, read-only **DFIR evidence collection**, and an **incident-response snapshot** mode — each of which can be enriched with **AI analysis** from Claude, OpenAI, Azure OpenAI, or a fully-local Ollama model.
|
|
32
|
+
|
|
33
|
+
- **Zero runtime dependencies.** Pure Python standard library — including the AI calls (raw `urllib`, no vendor SDKs). Nothing to vet, nothing to pin, runs in locked-down and air-gapped environments.
|
|
34
|
+
- **Cross-platform.** Linux, macOS, Windows. Python 3.8+.
|
|
35
|
+
- **Fast.** Probes run in parallel; a full triage completes in a few seconds.
|
|
36
|
+
- **Automation-friendly.** JSON output, JSON-lines audit log, webhook alerts, and meaningful exit codes.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Why it exists
|
|
41
|
+
|
|
42
|
+
Most "network test" tools answer *what* (ping failed) but not *why*. NetCheck encodes the logic an experienced engineer applies — if the gateway is unreachable, that's the root cause and the ISP doesn't matter; if the internet works by IP but your resolver doesn't answer, your DNS is broken, not the internet; if small packets pass but 1500-byte packets don't, you have an MTU black hole — and states the cause and the fix in plain language. The optional AI layer then adds expert narrative on top of those structured findings.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Install
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
# from source
|
|
50
|
+
git clone https://github.com/your-username/netcheck.git
|
|
51
|
+
cd netcheck
|
|
52
|
+
pip install .
|
|
53
|
+
|
|
54
|
+
# or run without installing
|
|
55
|
+
python3 -m netcheck
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
TOML config files need Python 3.11+ (or `pip install netcheck-cli[toml]`); JSON config works on any version. Nothing else is required.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Quick start
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
netcheck # full network triage + root-cause diagnosis
|
|
66
|
+
netcheck -t api.example.com # triage against a specific host
|
|
67
|
+
netcheck --full # add traceroute, MTU black-hole, IPv6 checks
|
|
68
|
+
netcheck security -t example.com # defensive security-posture assessment
|
|
69
|
+
netcheck incident -t example.com # diagnostics + security + host forensics
|
|
70
|
+
netcheck collect --evidence-dir ./ev # read-only forensic evidence bundle
|
|
71
|
+
netcheck verify ./ev/evidence-... # verify an evidence bundle's integrity
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Add `--ai` to any run to layer on AI analysis (see below), `-o report.md` to save a report, and `--json` for machine-readable output.
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## Modes
|
|
79
|
+
|
|
80
|
+
| Mode | What it does |
|
|
81
|
+
|---|---|
|
|
82
|
+
| `triage` *(default)* | Layered connectivity diagnostics + rule-based root-cause diagnosis. |
|
|
83
|
+
| `security` | Defensive posture review of an authorised target: TLS-version audit, weak-cipher check, certificate hygiene, OWASP security headers, exposed risky/management ports. |
|
|
84
|
+
| `incident` | Full IR snapshot: diagnostics **+** security assessment **+** read-only host forensics, written to one report with an evidence bundle. |
|
|
85
|
+
| `collect` | Read-only DFIR collection of volatile host network state (connections, listeners, ARP, routes, interfaces, DNS, firewall) into a hashed, manifested evidence bundle. |
|
|
86
|
+
| `verify <bundle>` | Re-hashes a previously collected bundle and confirms it hasn't been tampered with. |
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## AI-powered analysis
|
|
91
|
+
|
|
92
|
+
NetCheck can send its **structured** results to an LLM and get back a prioritised root-cause analysis and concrete remediation steps. Four providers are supported; pick based on your environment.
|
|
93
|
+
|
|
94
|
+
| Provider | Flag | API key (env var) | Notes |
|
|
95
|
+
|---|---|---|---|
|
|
96
|
+
| **Claude** (Anthropic) | `--ai-provider anthropic` | `ANTHROPIC_API_KEY` | Default model `claude-sonnet-4-6` (use `claude-opus-4-8` for deepest analysis). |
|
|
97
|
+
| **OpenAI / ChatGPT** | `--ai-provider openai` | `OPENAI_API_KEY` | Default `gpt-5.4-mini`. Works with any OpenAI-compatible server via `--ai-base-url`. |
|
|
98
|
+
| **Azure OpenAI** | `--ai-provider azure` | `AZURE_OPENAI_API_KEY` | Set `--ai-base-url https://<resource>.openai.azure.com` and `--ai-model <deployment>`. |
|
|
99
|
+
| **Ollama** (local) | `--ai-provider ollama` | *(none)* | Fully local / on-prem. **No data leaves the machine.** Default model `llama3.1`. |
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
# Validate provider connectivity first (great for setup / CI):
|
|
103
|
+
netcheck --ai-test --ai-provider ollama
|
|
104
|
+
|
|
105
|
+
# Claude-powered triage:
|
|
106
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
107
|
+
netcheck --ai --ai-provider anthropic
|
|
108
|
+
|
|
109
|
+
# Fully local analysis, nothing leaves the host:
|
|
110
|
+
netcheck --ai --ai-provider ollama --ai-model llama3.1
|
|
111
|
+
|
|
112
|
+
# AI-assisted security review:
|
|
113
|
+
netcheck security -t example.com --ai --ai-provider openai
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
**Privacy by design.** API keys are read **only** from environment variables — never from the config file, never logged. Before any request to a *cloud* provider, NetCheck redacts internal IPs, MAC addresses, and the local hostname (public IPs are kept so analysis stays useful). Use `--no-redact` to disable, or use **Ollama** for zero data egress. The prompts never include the host's internal addressing in the first place beyond what the checks surface, and redaction is applied on top of that.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Security posture assessment
|
|
121
|
+
|
|
122
|
+
`netcheck security -t <host>` performs a **defensive, read-only** review of a host you **own or are explicitly authorised to assess**:
|
|
123
|
+
|
|
124
|
+
- **TLS protocol audit** — flags deprecated TLS 1.0/1.1 support; confirms modern TLS 1.2/1.3 and reports the negotiated cipher (weak ciphers raised as warnings).
|
|
125
|
+
- **Certificate hygiene** — validity, expiry window (warns < 30 days, fails < 15), issuer, hostname match, self-signed detection.
|
|
126
|
+
- **HTTP security headers** — checks for HSTS, CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy (per OWASP Secure Headers).
|
|
127
|
+
- **Exposed services** — reports reachable risky/management/database ports (Telnet, SMB, RDP, MySQL, Redis, MongoDB, …).
|
|
128
|
+
|
|
129
|
+
These are configuration/hygiene checks only — **no exploitation, no credential testing, no network scanning** beyond the single specified target. It's blue-team auditing, comparable to what a CIS benchmark or OWASP review inspects.
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## Forensics & incident response
|
|
134
|
+
|
|
135
|
+
`netcheck collect` performs **read-only** DFIR triage collection of volatile host network state, ordered by volatility (RFC 3227 spirit): active connections, listening sockets, ARP/neighbour table, routing table, interfaces, DNS configuration, firewall rules, and the process list. It **never modifies the host**.
|
|
136
|
+
|
|
137
|
+
Every artifact is hashed (SHA-256) and recorded in a `manifest.json` with timestamps, the collecting operator, an optional case ID, and a bundle-level integrity hash — a tamper-evident evidence bundle:
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
netcheck collect --evidence-dir ./evidence --operator analyst1 --case-id IR-2026-007
|
|
141
|
+
netcheck verify ./evidence/evidence-20260608T063439Z # confirm integrity later
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`netcheck incident` chains diagnostics + security + forensics into a single timestamped IR report with its evidence bundle, and (with `--ai`) an AI-generated incident analysis following standard IR phases (scope → severity → containment → eradication/recovery → further evidence to collect).
|
|
145
|
+
|
|
146
|
+
Collection degrades gracefully: tools that need elevated privileges or aren't installed are skipped and noted in the manifest rather than failing the run.
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## Configuration
|
|
151
|
+
|
|
152
|
+
Settings resolve in order: **CLI flags → environment variables → config file → defaults.** Copy `netcheck.example.toml` to `netcheck.toml` (or use JSON). The config file is **safe to commit** — secrets never live in it.
|
|
153
|
+
|
|
154
|
+
```toml
|
|
155
|
+
target = "cloudflare.com"
|
|
156
|
+
ports = [80, 443, 22, 53]
|
|
157
|
+
operator = "netops"
|
|
158
|
+
log_file = "/var/log/netcheck/audit.jsonl"
|
|
159
|
+
|
|
160
|
+
[ai]
|
|
161
|
+
enabled = false
|
|
162
|
+
provider = "ollama"
|
|
163
|
+
redact = true
|
|
164
|
+
|
|
165
|
+
[notify]
|
|
166
|
+
webhook_url = ""
|
|
167
|
+
on_severity = "WARN"
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Useful environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `OLLAMA_HOST`, `NETCHECK_TARGET`, `NETCHECK_AI_PROVIDER`, `NETCHECK_WEBHOOK_URL`, `NETCHECK_OPERATOR`.
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## Output, alerting & automation
|
|
175
|
+
|
|
176
|
+
- **Markdown report:** `-o report.md` — grouped by Diagnostic / Security / Forensic, with the diagnosis and any AI analysis.
|
|
177
|
+
- **JSON:** `--json` (alongside the dashboard) or `--json-only` (pipe-friendly) — stable schema `netcheck-report-2`.
|
|
178
|
+
- **Audit log:** `--log-file audit.jsonl` appends one JSON object per run (verdict, per-check status, top finding) — ready for SIEM ingestion.
|
|
179
|
+
- **Webhook alerts:** `--webhook <url>` posts a Slack/Teams/Mattermost-compatible JSON payload when the verdict reaches the configured severity.
|
|
180
|
+
|
|
181
|
+
### Exit codes
|
|
182
|
+
|
|
183
|
+
| Code | Meaning |
|
|
184
|
+
|---|---|
|
|
185
|
+
| `0` | HEALTHY — all checks passed (or bundle INTACT). |
|
|
186
|
+
| `1` | DEGRADED — at least one warning. |
|
|
187
|
+
| `2` | DOWN — at least one failure (or bundle INTEGRITY FAILURE). |
|
|
188
|
+
|
|
189
|
+
These make NetCheck easy to wire into cron, CI, monitoring, or runbooks.
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## Responsible use
|
|
194
|
+
|
|
195
|
+
NetCheck's defaults touch only public infrastructure (Cloudflare/Google anycast resolvers, the configured target). The `security` and `collect`/`incident` modes are for systems you **own or are explicitly authorised to assess**. NetCheck performs read-only assessment and collection only — it does not exploit, scan networks, or test credentials.
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## Architecture
|
|
200
|
+
|
|
201
|
+
```
|
|
202
|
+
netcheck/
|
|
203
|
+
├── core.py status model + low-level primitives (ping, TCP, DNS, HTTP, TLS)
|
|
204
|
+
├── checks.py layered diagnostic checks + runner
|
|
205
|
+
├── security.py defensive posture checks (TLS/cert/headers/exposed services)
|
|
206
|
+
├── forensics.py read-only evidence collection + integrity verification
|
|
207
|
+
├── diagnosis.py rule-based root-cause engine
|
|
208
|
+
├── ai.py provider abstraction (Claude/OpenAI/Azure/Ollama) + redaction
|
|
209
|
+
├── config.py config + secret handling
|
|
210
|
+
├── report.py Markdown / JSON / audit-log renderers
|
|
211
|
+
├── notify.py webhook notifier
|
|
212
|
+
└── cli.py orchestration + live dashboard
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
The rule-based engine runs locally and instantly; the AI layer is strictly additive and optional. No third-party packages at runtime.
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## Testing
|
|
220
|
+
|
|
221
|
+
```bash
|
|
222
|
+
python3 -m unittest discover -s tests -v
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
The suite (stdlib `unittest`, no extra deps) covers the status model, DNS packet parse, TCP connectivity, **all four AI providers via local mock servers** (including a test that the internal-IP redaction actually happens before data leaves for cloud providers), the diagnosis rules, forensic collection + tamper detection, config loading, and report generation. Live TLS/certificate checks run against real infrastructure and skip automatically when offline.
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## License
|
|
230
|
+
|
|
231
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# NetCheck
|
|
2
|
+
|
|
3
|
+
**Enterprise network triage, security posture, and incident-response/forensics in one command — with optional AI analysis.**
|
|
4
|
+
|
|
5
|
+
NetCheck runs the full network-troubleshooting workflow (interface → gateway → internet → DNS → ports → HTTP/captive-portal → TLS → quality, plus optional traceroute/MTU/IPv6), then **diagnoses the root cause** instead of just dumping raw output. On top of that it adds a defensive **security-posture assessment**, read-only **DFIR evidence collection**, and an **incident-response snapshot** mode — each of which can be enriched with **AI analysis** from Claude, OpenAI, Azure OpenAI, or a fully-local Ollama model.
|
|
6
|
+
|
|
7
|
+
- **Zero runtime dependencies.** Pure Python standard library — including the AI calls (raw `urllib`, no vendor SDKs). Nothing to vet, nothing to pin, runs in locked-down and air-gapped environments.
|
|
8
|
+
- **Cross-platform.** Linux, macOS, Windows. Python 3.8+.
|
|
9
|
+
- **Fast.** Probes run in parallel; a full triage completes in a few seconds.
|
|
10
|
+
- **Automation-friendly.** JSON output, JSON-lines audit log, webhook alerts, and meaningful exit codes.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Why it exists
|
|
15
|
+
|
|
16
|
+
Most "network test" tools answer *what* (ping failed) but not *why*. NetCheck encodes the logic an experienced engineer applies — if the gateway is unreachable, that's the root cause and the ISP doesn't matter; if the internet works by IP but your resolver doesn't answer, your DNS is broken, not the internet; if small packets pass but 1500-byte packets don't, you have an MTU black hole — and states the cause and the fix in plain language. The optional AI layer then adds expert narrative on top of those structured findings.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Install
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
# from source
|
|
24
|
+
git clone https://github.com/your-username/netcheck.git
|
|
25
|
+
cd netcheck
|
|
26
|
+
pip install .
|
|
27
|
+
|
|
28
|
+
# or run without installing
|
|
29
|
+
python3 -m netcheck
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
TOML config files need Python 3.11+ (or `pip install netcheck-cli[toml]`); JSON config works on any version. Nothing else is required.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Quick start
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
netcheck # full network triage + root-cause diagnosis
|
|
40
|
+
netcheck -t api.example.com # triage against a specific host
|
|
41
|
+
netcheck --full # add traceroute, MTU black-hole, IPv6 checks
|
|
42
|
+
netcheck security -t example.com # defensive security-posture assessment
|
|
43
|
+
netcheck incident -t example.com # diagnostics + security + host forensics
|
|
44
|
+
netcheck collect --evidence-dir ./ev # read-only forensic evidence bundle
|
|
45
|
+
netcheck verify ./ev/evidence-... # verify an evidence bundle's integrity
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Add `--ai` to any run to layer on AI analysis (see below), `-o report.md` to save a report, and `--json` for machine-readable output.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Modes
|
|
53
|
+
|
|
54
|
+
| Mode | What it does |
|
|
55
|
+
|---|---|
|
|
56
|
+
| `triage` *(default)* | Layered connectivity diagnostics + rule-based root-cause diagnosis. |
|
|
57
|
+
| `security` | Defensive posture review of an authorised target: TLS-version audit, weak-cipher check, certificate hygiene, OWASP security headers, exposed risky/management ports. |
|
|
58
|
+
| `incident` | Full IR snapshot: diagnostics **+** security assessment **+** read-only host forensics, written to one report with an evidence bundle. |
|
|
59
|
+
| `collect` | Read-only DFIR collection of volatile host network state (connections, listeners, ARP, routes, interfaces, DNS, firewall) into a hashed, manifested evidence bundle. |
|
|
60
|
+
| `verify <bundle>` | Re-hashes a previously collected bundle and confirms it hasn't been tampered with. |
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## AI-powered analysis
|
|
65
|
+
|
|
66
|
+
NetCheck can send its **structured** results to an LLM and get back a prioritised root-cause analysis and concrete remediation steps. Four providers are supported; pick based on your environment.
|
|
67
|
+
|
|
68
|
+
| Provider | Flag | API key (env var) | Notes |
|
|
69
|
+
|---|---|---|---|
|
|
70
|
+
| **Claude** (Anthropic) | `--ai-provider anthropic` | `ANTHROPIC_API_KEY` | Default model `claude-sonnet-4-6` (use `claude-opus-4-8` for deepest analysis). |
|
|
71
|
+
| **OpenAI / ChatGPT** | `--ai-provider openai` | `OPENAI_API_KEY` | Default `gpt-5.4-mini`. Works with any OpenAI-compatible server via `--ai-base-url`. |
|
|
72
|
+
| **Azure OpenAI** | `--ai-provider azure` | `AZURE_OPENAI_API_KEY` | Set `--ai-base-url https://<resource>.openai.azure.com` and `--ai-model <deployment>`. |
|
|
73
|
+
| **Ollama** (local) | `--ai-provider ollama` | *(none)* | Fully local / on-prem. **No data leaves the machine.** Default model `llama3.1`. |
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
# Validate provider connectivity first (great for setup / CI):
|
|
77
|
+
netcheck --ai-test --ai-provider ollama
|
|
78
|
+
|
|
79
|
+
# Claude-powered triage:
|
|
80
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
81
|
+
netcheck --ai --ai-provider anthropic
|
|
82
|
+
|
|
83
|
+
# Fully local analysis, nothing leaves the host:
|
|
84
|
+
netcheck --ai --ai-provider ollama --ai-model llama3.1
|
|
85
|
+
|
|
86
|
+
# AI-assisted security review:
|
|
87
|
+
netcheck security -t example.com --ai --ai-provider openai
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**Privacy by design.** API keys are read **only** from environment variables — never from the config file, never logged. Before any request to a *cloud* provider, NetCheck redacts internal IPs, MAC addresses, and the local hostname (public IPs are kept so analysis stays useful). Use `--no-redact` to disable, or use **Ollama** for zero data egress. The prompts never include the host's internal addressing in the first place beyond what the checks surface, and redaction is applied on top of that.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## Security posture assessment
|
|
95
|
+
|
|
96
|
+
`netcheck security -t <host>` performs a **defensive, read-only** review of a host you **own or are explicitly authorised to assess**:
|
|
97
|
+
|
|
98
|
+
- **TLS protocol audit** — flags deprecated TLS 1.0/1.1 support; confirms modern TLS 1.2/1.3 and reports the negotiated cipher (weak ciphers raised as warnings).
|
|
99
|
+
- **Certificate hygiene** — validity, expiry window (warns < 30 days, fails < 15), issuer, hostname match, self-signed detection.
|
|
100
|
+
- **HTTP security headers** — checks for HSTS, CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy (per OWASP Secure Headers).
|
|
101
|
+
- **Exposed services** — reports reachable risky/management/database ports (Telnet, SMB, RDP, MySQL, Redis, MongoDB, …).
|
|
102
|
+
|
|
103
|
+
These are configuration/hygiene checks only — **no exploitation, no credential testing, no network scanning** beyond the single specified target. It's blue-team auditing, comparable to what a CIS benchmark or OWASP review inspects.
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## Forensics & incident response
|
|
108
|
+
|
|
109
|
+
`netcheck collect` performs **read-only** DFIR triage collection of volatile host network state, ordered by volatility (RFC 3227 spirit): active connections, listening sockets, ARP/neighbour table, routing table, interfaces, DNS configuration, firewall rules, and the process list. It **never modifies the host**.
|
|
110
|
+
|
|
111
|
+
Every artifact is hashed (SHA-256) and recorded in a `manifest.json` with timestamps, the collecting operator, an optional case ID, and a bundle-level integrity hash — a tamper-evident evidence bundle:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
netcheck collect --evidence-dir ./evidence --operator analyst1 --case-id IR-2026-007
|
|
115
|
+
netcheck verify ./evidence/evidence-20260608T063439Z # confirm integrity later
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`netcheck incident` chains diagnostics + security + forensics into a single timestamped IR report with its evidence bundle, and (with `--ai`) an AI-generated incident analysis following standard IR phases (scope → severity → containment → eradication/recovery → further evidence to collect).
|
|
119
|
+
|
|
120
|
+
Collection degrades gracefully: tools that need elevated privileges or aren't installed are skipped and noted in the manifest rather than failing the run.
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## Configuration
|
|
125
|
+
|
|
126
|
+
Settings resolve in order: **CLI flags → environment variables → config file → defaults.** Copy `netcheck.example.toml` to `netcheck.toml` (or use JSON). The config file is **safe to commit** — secrets never live in it.
|
|
127
|
+
|
|
128
|
+
```toml
|
|
129
|
+
target = "cloudflare.com"
|
|
130
|
+
ports = [80, 443, 22, 53]
|
|
131
|
+
operator = "netops"
|
|
132
|
+
log_file = "/var/log/netcheck/audit.jsonl"
|
|
133
|
+
|
|
134
|
+
[ai]
|
|
135
|
+
enabled = false
|
|
136
|
+
provider = "ollama"
|
|
137
|
+
redact = true
|
|
138
|
+
|
|
139
|
+
[notify]
|
|
140
|
+
webhook_url = ""
|
|
141
|
+
on_severity = "WARN"
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Useful environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `OLLAMA_HOST`, `NETCHECK_TARGET`, `NETCHECK_AI_PROVIDER`, `NETCHECK_WEBHOOK_URL`, `NETCHECK_OPERATOR`.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Output, alerting & automation
|
|
149
|
+
|
|
150
|
+
- **Markdown report:** `-o report.md` — grouped by Diagnostic / Security / Forensic, with the diagnosis and any AI analysis.
|
|
151
|
+
- **JSON:** `--json` (alongside the dashboard) or `--json-only` (pipe-friendly) — stable schema `netcheck-report-2`.
|
|
152
|
+
- **Audit log:** `--log-file audit.jsonl` appends one JSON object per run (verdict, per-check status, top finding) — ready for SIEM ingestion.
|
|
153
|
+
- **Webhook alerts:** `--webhook <url>` posts a Slack/Teams/Mattermost-compatible JSON payload when the verdict reaches the configured severity.
|
|
154
|
+
|
|
155
|
+
### Exit codes
|
|
156
|
+
|
|
157
|
+
| Code | Meaning |
|
|
158
|
+
|---|---|
|
|
159
|
+
| `0` | HEALTHY — all checks passed (or bundle INTACT). |
|
|
160
|
+
| `1` | DEGRADED — at least one warning. |
|
|
161
|
+
| `2` | DOWN — at least one failure (or bundle INTEGRITY FAILURE). |
|
|
162
|
+
|
|
163
|
+
These make NetCheck easy to wire into cron, CI, monitoring, or runbooks.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Responsible use
|
|
168
|
+
|
|
169
|
+
NetCheck's defaults touch only public infrastructure (Cloudflare/Google anycast resolvers, the configured target). The `security` and `collect`/`incident` modes are for systems you **own or are explicitly authorised to assess**. NetCheck performs read-only assessment and collection only — it does not exploit, scan networks, or test credentials.
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## Architecture
|
|
174
|
+
|
|
175
|
+
```
|
|
176
|
+
netcheck/
|
|
177
|
+
├── core.py status model + low-level primitives (ping, TCP, DNS, HTTP, TLS)
|
|
178
|
+
├── checks.py layered diagnostic checks + runner
|
|
179
|
+
├── security.py defensive posture checks (TLS/cert/headers/exposed services)
|
|
180
|
+
├── forensics.py read-only evidence collection + integrity verification
|
|
181
|
+
├── diagnosis.py rule-based root-cause engine
|
|
182
|
+
├── ai.py provider abstraction (Claude/OpenAI/Azure/Ollama) + redaction
|
|
183
|
+
├── config.py config + secret handling
|
|
184
|
+
├── report.py Markdown / JSON / audit-log renderers
|
|
185
|
+
├── notify.py webhook notifier
|
|
186
|
+
└── cli.py orchestration + live dashboard
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
The rule-based engine runs locally and instantly; the AI layer is strictly additive and optional. No third-party packages at runtime.
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## Testing
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
python3 -m unittest discover -s tests -v
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
The suite (stdlib `unittest`, no extra deps) covers the status model, DNS packet parse, TCP connectivity, **all four AI providers via local mock servers** (including a test that the internal-IP redaction actually happens before data leaves for cloud providers), the diagnosis rules, forensic collection + tamper detection, config loading, and report generation. Live TLS/certificate checks run against real infrastructure and skip automatically when offline.
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## License
|
|
204
|
+
|
|
205
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""
|
|
2
|
+
NetCheck — enterprise network triage, security posture, and IR/forensics
|
|
3
|
+
with optional AI analysis (Claude / OpenAI / Azure / Ollama).
|
|
4
|
+
|
|
5
|
+
Standard-library only at runtime (AI calls use urllib, no SDKs) so it runs in
|
|
6
|
+
locked-down and air-gapped environments.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
__version__ = "2.0.0"
|
|
10
|
+
__all__ = ["__version__"]
|