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.
@@ -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__"]
@@ -0,0 +1,5 @@
1
+ import sys
2
+ from .cli import main
3
+
4
+ if __name__ == "__main__":
5
+ sys.exit(main())