netconverter-cli 0.4.4__tar.gz → 0.6.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.
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/CHANGELOG.md +47 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/PKG-INFO +14 -9
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/README.md +12 -8
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/COMMANDS.md +98 -13
- netconverter_cli-0.6.0/docs/PRIVACY.md +256 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/README.md +3 -2
- netconverter_cli-0.6.0/docs/connect/compatibility.md +42 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/openclaw.md +4 -3
- netconverter_cli-0.6.0/docs/connect/other-assistants.md +47 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/pyproject.toml +3 -2
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/__init__.py +1 -1
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/clerk.py +19 -9
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/cli.py +73 -20
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/connect.py +68 -17
- netconverter_cli-0.6.0/src/netconverter_cli/credential_file.py +311 -0
- netconverter_cli-0.6.0/src/netconverter_cli/credentials.py +373 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/drafts.py +16 -8
- netconverter_cli-0.6.0/src/netconverter_cli/exposure.py +392 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/guided.py +41 -7
- netconverter_cli-0.6.0/src/netconverter_cli/mcp_client_features.py +212 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/mcp_server.py +209 -18
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/mcp_workflows.py +2 -2
- netconverter_cli-0.6.0/src/netconverter_cli/privacy_apply.py +248 -0
- netconverter_cli-0.6.0/src/netconverter_cli/privacy_cli.py +104 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/remote_mcp.py +41 -2
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/conftest.py +8 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_cli_020.py +4 -2
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_connect_030.py +1 -1
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_connect_031.py +1 -1
- netconverter_cli-0.6.0/tests/test_connect_compat_014.py +97 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_connect_openclaw_014.py +6 -6
- netconverter_cli-0.6.0/tests/test_credential_file_010.py +274 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_drafts.py +28 -1
- netconverter_cli-0.6.0/tests/test_exposure_levels_013.py +301 -0
- netconverter_cli-0.6.0/tests/test_guided_full_api_019.py +194 -0
- netconverter_cli-0.6.0/tests/test_guided_mapping_012.py +128 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_mcp.py +7 -6
- netconverter_cli-0.6.0/tests/test_mcp_features_020.py +243 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_mcp_workflows.py +1 -1
- netconverter_cli-0.6.0/tests/test_privacy_apply_013.py +145 -0
- netconverter_cli-0.6.0/tests/test_privacy_cli_013.py +152 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_strict_default_011.py +24 -16
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_strict_view_015.py +15 -9
- netconverter_cli-0.4.4/docs/PRIVACY.md +0 -148
- netconverter_cli-0.4.4/docs/connect/other-assistants.md +0 -32
- netconverter_cli-0.4.4/src/netconverter_cli/credentials.py +0 -216
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/.gitignore +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/LICENSE +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/QUICK_START.md +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/SECURITY.md +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/RELEASING.md +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/VERIFICATION.md +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/chatgpt.md +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/claude-ai.md +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/claude-code.md +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/claude-desktop.md +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/getting-access.md +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/guided-workflows.md +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/examples/README.md +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/activity.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/api.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/backend.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/branding.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/catalog.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/commands.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/connect_openclaw.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/controller.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/design_catalog.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/draft_cli.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/draft_io.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/errors.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/guided_operations.json +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/guided_projects.json +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/job_options.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/license.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/one_shot.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/palette.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/presentation.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/privacy.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/project_cli.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/projects.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/providers.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/setup.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/summary.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/tui.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/update.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/walkthrough.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/windows_draft_io.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/workspace.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/fixtures/jobs/opt_4056e02e5b66.json +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/fixtures/jobs/tra_4058ef406cd6.json +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/fixtures/jobs/tra_running.json +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/fixtures/jobs/val_9f9acb9b5a59.json +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/fixtures/jobs/val_9f9acb9b5a59.sarif +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_autodetect_v5.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_boundaries.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_bridge_polish_021.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_clerk.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_clerk_host_binding.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_connect_direct_entry.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_download_analysis.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_draft_cli.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_draft_io.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_draft_jobs.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_errors_009.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_folders_cd_ls.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_help_008.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_inline.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_keyring_bus_017.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_keyring_timeout_010.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_license.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_mcp_auth_016.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_mcp_jobs.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_options_011_019.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_polish_028.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_presentation.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_projects.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_protocols.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_readonly_workspace.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_sessions.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_setup.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_signin_default.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_stage_029.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_summary_007.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_update.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_vendor_error_022.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_walkthrough.py +0 -0
- {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_windows_draft_io.py +0 -0
|
@@ -1,5 +1,52 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.6.0 — 2026-10-30
|
|
4
|
+
|
|
5
|
+
- Guided drafts retain the server-advertised ASA target format (Palo Alto SET,
|
|
6
|
+
standalone XML, or Panorama). Preparation refuses targets absent from the
|
|
7
|
+
credential's current capabilities before reading a source file, and rejects a
|
|
8
|
+
response that substitutes another target. Server rollout qualification still
|
|
9
|
+
controls availability.
|
|
10
|
+
|
|
11
|
+
## 0.5.0 — 2026-10-29
|
|
12
|
+
|
|
13
|
+
**Upgrade note.** Each folder now has an exposure level for AI assistants, default
|
|
14
|
+
`masked`, and it is the ceiling: `--full` / `NETCONVERTER_MCP_VIEW=full` widen the view
|
|
15
|
+
only after `netconverter privacy level full` (confirmed in a terminal); `--strict` means
|
|
16
|
+
masked. `connect` no longer writes `--strict`; run `netconverter connect <client>` again
|
|
17
|
+
to drop it.
|
|
18
|
+
|
|
19
|
+
- New: guided mapping from your AI assistant. The bridge offers the server's
|
|
20
|
+
`get_mapping_questions`, `validate_mapping` and `apply_mapping_answers`: decision-only
|
|
21
|
+
questions (zones, interfaces, conversion options) where every configuration name is a
|
|
22
|
+
token, answers checked before anything changes, and a new conversion queued only after
|
|
23
|
+
you confirm it in the assistant's own dialog. Not available at level `none`.
|
|
24
|
+
- New: `netconverter privacy level none|masked|selected|full` and `privacy status`.
|
|
25
|
+
Raising a level needs a confirmation typed in a terminal; every change is audited in
|
|
26
|
+
`.netconverter/privacy-audit.jsonl`; no MCP tool can change it. The bridge sends the
|
|
27
|
+
level on every request and filters every result to it; secrets (PSKs, SNMP communities,
|
|
28
|
+
hashes, passwords) are removed at every level.
|
|
29
|
+
- New: `netconverter privacy apply --client claude-code|cursor|gemini|codex|openclaw`
|
|
30
|
+
keeps an assistant's own file tools out of the folder (diff, yes, `.bak`, idempotent;
|
|
31
|
+
codex and openclaw print the settings).
|
|
32
|
+
- New: headless sign-in survives a reboot. Where no OS keyring is reachable (SSH,
|
|
33
|
+
containers), the sign-in and stored keys go to a passphrase-encrypted file (AES-256-GCM,
|
|
34
|
+
scrypt, mode 0600). Choose it with `login --store file` or
|
|
35
|
+
`NETCONVERTER_CREDENTIAL_STORE`; the passphrase comes from
|
|
36
|
+
`NETCONVERTER_CREDENTIAL_PASSPHRASE` or `…_PASSPHRASE_FILE`. `login` and `whoami` name
|
|
37
|
+
the store; the threat model is in docs/PRIVACY.md. Adds the `cryptography` dependency.
|
|
38
|
+
- App: on the full API, `/convert` offers the Advanced and Zone mapping screens after the
|
|
39
|
+
target, sent as a YAML v2 document.
|
|
40
|
+
- Bridge: `outputSchema` for every local tool; MCP prompts `guided-migration` and
|
|
41
|
+
`mapping-review`; `submit_file` asks for upload confirmation in the assistant's own
|
|
42
|
+
dialog when it supports elicitation (a decline sends nothing).
|
|
43
|
+
- `connect gemini` writes an `env` block so Gemini no longer strips the NetConverter
|
|
44
|
+
variables, and says to trust the folder; `connect codex` forwards them with `env_vars`.
|
|
45
|
+
New `connect devin` (Devin Desktop, formerly Windsurf; `windsurf` is kept for the legacy
|
|
46
|
+
Cascade agent). Claude Desktop on Linux gets the manual Edit Config step.
|
|
47
|
+
- docs/connect/compatibility.md: each client's config path and format, checked against
|
|
48
|
+
vendor docs on 2026-10-29.
|
|
49
|
+
|
|
3
50
|
## 0.4.4 — 2026-10-29
|
|
4
51
|
|
|
5
52
|
**License change.** From 0.4.4 the client is licensed by ValeronLabs LLC for use with
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: netconverter-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.6.0
|
|
4
4
|
Summary: NetConverter CLI — any-vendor network configuration migration, validation and optimization, and a local MCP bridge for your AI assistant
|
|
5
5
|
Project-URL: Homepage, https://netconverter.ai
|
|
6
6
|
Project-URL: Repository, https://github.com/valeronlabs/netconverter_terminals
|
|
@@ -26,6 +26,7 @@ Classifier: Topic :: System :: Networking
|
|
|
26
26
|
Classifier: Topic :: System :: Networking :: Firewalls
|
|
27
27
|
Classifier: Topic :: Utilities
|
|
28
28
|
Requires-Python: >=3.12
|
|
29
|
+
Requires-Dist: cryptography==50.0.2
|
|
29
30
|
Requires-Dist: httpx==0.28.1
|
|
30
31
|
Requires-Dist: keyring==25.7.0
|
|
31
32
|
Requires-Dist: pydantic==2.13.5
|
|
@@ -41,7 +42,7 @@ Description-Content-Type: text/markdown
|
|
|
41
42
|
NetConverter — by ValeronLabs LLC.
|
|
42
43
|
|
|
43
44
|
```text
|
|
44
|
-
◆ NetConverter v0.
|
|
45
|
+
◆ NetConverter v0.6.0 ● Server ◆ Bridge claude-code · 2m ago
|
|
45
46
|
▍ Start
|
|
46
47
|
▍ /convert Migrate a configuration to another vendor
|
|
47
48
|
▍ /validate Check a configuration before migrating
|
|
@@ -129,7 +130,7 @@ Step-by-step guides for every assistant (Claude, ChatGPT, Cursor, Gemini CLI, Co
|
|
|
129
130
|
[docs/connect](docs/connect/README.md).
|
|
130
131
|
|
|
131
132
|
```sh
|
|
132
|
-
netconverter connect claude-code # or claude-desktop, cursor, vscode, codex, gemini, windsurf, lmstudio
|
|
133
|
+
netconverter connect claude-code # or claude-desktop, cursor, vscode, codex, gemini, devin, windsurf, lmstudio
|
|
133
134
|
netconverter connect --all # every assistant found on this computer
|
|
134
135
|
netconverter connect chatgpt # ChatGPT / claude.ai: remote-connector setup steps
|
|
135
136
|
```
|
|
@@ -143,15 +144,19 @@ Then ask your assistant, for example: *"Validate edge-fw.conf and tell me what i
|
|
|
143
144
|
|
|
144
145
|
Bridge tools: `submit_file`, `job_status`, `wait_for_job`, `account`, `download`,
|
|
145
146
|
plus an allowlist of NetConverter's read-only tools (reports, evidence, NAT, flows,
|
|
146
|
-
knowledge base).
|
|
147
|
-
|
|
148
|
-
|
|
147
|
+
knowledge base). What the assistant sees is this folder's **exposure level**
|
|
148
|
+
(`netconverter privacy level none|masked|selected|full`, default **masked**: the strict view,
|
|
149
|
+
names as tokens, addresses masked, no configuration content); secrets are removed at every
|
|
150
|
+
level, and raising the level needs a confirmation typed in a terminal (docs/PRIVACY.md).
|
|
151
|
+
`netconverter privacy apply --client claude-code` (also cursor, gemini; codex and openclaw
|
|
152
|
+
print the settings) keeps the assistant's own file tools out of the folder. Job `options` from an assistant pass an
|
|
149
153
|
allowlist with type checks: an unknown or reserved key (the file, vendors, job type, a
|
|
150
154
|
decisions document) is refused naming it, never silently sent.
|
|
151
155
|
|
|
152
|
-
**Upgrading from 0.4.x:**
|
|
153
|
-
|
|
154
|
-
|
|
156
|
+
**Upgrading from 0.4.x:** `--full` (or `NETCONVERTER_MCP_VIEW=full`) no longer widens the
|
|
157
|
+
view on its own; run `netconverter privacy level full` in a terminal for the folder. Run
|
|
158
|
+
`netconverter connect <assistant>` again to drop the `--strict` that 0.4.4 wrote, which would
|
|
159
|
+
hold the assistant at masked.
|
|
155
160
|
|
|
156
161
|
Inside the app, `/activity` and the header's **Bridge** pill show what your AI did
|
|
157
162
|
through the bridge — paths, sizes, SHA-256 and job IDs only.
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
NetConverter — by ValeronLabs LLC.
|
|
8
8
|
|
|
9
9
|
```text
|
|
10
|
-
◆ NetConverter v0.
|
|
10
|
+
◆ NetConverter v0.6.0 ● Server ◆ Bridge claude-code · 2m ago
|
|
11
11
|
▍ Start
|
|
12
12
|
▍ /convert Migrate a configuration to another vendor
|
|
13
13
|
▍ /validate Check a configuration before migrating
|
|
@@ -95,7 +95,7 @@ Step-by-step guides for every assistant (Claude, ChatGPT, Cursor, Gemini CLI, Co
|
|
|
95
95
|
[docs/connect](docs/connect/README.md).
|
|
96
96
|
|
|
97
97
|
```sh
|
|
98
|
-
netconverter connect claude-code # or claude-desktop, cursor, vscode, codex, gemini, windsurf, lmstudio
|
|
98
|
+
netconverter connect claude-code # or claude-desktop, cursor, vscode, codex, gemini, devin, windsurf, lmstudio
|
|
99
99
|
netconverter connect --all # every assistant found on this computer
|
|
100
100
|
netconverter connect chatgpt # ChatGPT / claude.ai: remote-connector setup steps
|
|
101
101
|
```
|
|
@@ -109,15 +109,19 @@ Then ask your assistant, for example: *"Validate edge-fw.conf and tell me what i
|
|
|
109
109
|
|
|
110
110
|
Bridge tools: `submit_file`, `job_status`, `wait_for_job`, `account`, `download`,
|
|
111
111
|
plus an allowlist of NetConverter's read-only tools (reports, evidence, NAT, flows,
|
|
112
|
-
knowledge base).
|
|
113
|
-
|
|
114
|
-
|
|
112
|
+
knowledge base). What the assistant sees is this folder's **exposure level**
|
|
113
|
+
(`netconverter privacy level none|masked|selected|full`, default **masked**: the strict view,
|
|
114
|
+
names as tokens, addresses masked, no configuration content); secrets are removed at every
|
|
115
|
+
level, and raising the level needs a confirmation typed in a terminal (docs/PRIVACY.md).
|
|
116
|
+
`netconverter privacy apply --client claude-code` (also cursor, gemini; codex and openclaw
|
|
117
|
+
print the settings) keeps the assistant's own file tools out of the folder. Job `options` from an assistant pass an
|
|
115
118
|
allowlist with type checks: an unknown or reserved key (the file, vendors, job type, a
|
|
116
119
|
decisions document) is refused naming it, never silently sent.
|
|
117
120
|
|
|
118
|
-
**Upgrading from 0.4.x:**
|
|
119
|
-
|
|
120
|
-
|
|
121
|
+
**Upgrading from 0.4.x:** `--full` (or `NETCONVERTER_MCP_VIEW=full`) no longer widens the
|
|
122
|
+
view on its own; run `netconverter privacy level full` in a terminal for the folder. Run
|
|
123
|
+
`netconverter connect <assistant>` again to drop the `--strict` that 0.4.4 wrote, which would
|
|
124
|
+
hold the assistant at masked.
|
|
121
125
|
|
|
122
126
|
Inside the app, `/activity` and the header's **Bridge** pill show what your AI did
|
|
123
127
|
through the bridge — paths, sizes, SHA-256 and job IDs only.
|
|
@@ -47,6 +47,17 @@ Questions need a completed job: use `/resume` first. Selecting another file or
|
|
|
47
47
|
|
|
48
48
|
The app shows the profile in the header and in `/refresh`.
|
|
49
49
|
|
|
50
|
+
Where a sign-in or key is kept: the OS credential store when one is available, otherwise
|
|
51
|
+
an encrypted credential file (headless machines, containers). `netconverter login --store
|
|
52
|
+
file` (or `keyring`, `auto`) chooses for that sign-in, for example `netconverter login
|
|
53
|
+
--device --store file` on an SSH host; `NETCONVERTER_CREDENTIAL_STORE=auto|keyring|file`
|
|
54
|
+
keeps the choice. The file needs a passphrase of at least 12 characters:
|
|
55
|
+
`NETCONVERTER_CREDENTIAL_PASSPHRASE`, `NETCONVERTER_CREDENTIAL_PASSPHRASE_FILE` (a path to a
|
|
56
|
+
file holding it), or a hidden prompt on a terminal. `NETCONVERTER_CREDENTIAL_FILE` moves the
|
|
57
|
+
file. `login` and `whoami` print the store in use. An AI client that starts `netconverter
|
|
58
|
+
mcp` must pass the passphrase variable in the server's `env`. Encryption details and the
|
|
59
|
+
threat model: [PRIVACY.md](PRIVACY.md#encrypted-credential-file-headless-machines).
|
|
60
|
+
|
|
50
61
|
## Conversion settings
|
|
51
62
|
|
|
52
63
|
Full API: choose the target; the server applies its defaults for everything else.
|
|
@@ -68,6 +79,12 @@ unknown key, or a request field (`source_config`, vendors, `technology`, `job_ty
|
|
|
68
79
|
`manual_mappings`) is refused before anything is uploaded, naming it. The full API also accepts
|
|
69
80
|
`selected_device_groups`, `file_name`, `optimization_options` (optimize) and a whole `yaml_v2`.
|
|
70
81
|
|
|
82
|
+
In the app, `/convert` on the full API asks **Conversion settings** after the target: *Use
|
|
83
|
+
NetConverter's defaults* sends no decisions; *Customize* walks the same screens a pilot key
|
|
84
|
+
gets (Panorama scope for a Panorama target, unused-object cleanup, App-ID, profiles, logging,
|
|
85
|
+
explicit deny, a profile group for Palo Alto targets, and the zone mapping), each with a
|
|
86
|
+
server-default choice, and the review's Submit sends them as the YAML v2 document above.
|
|
87
|
+
|
|
71
88
|
### YAML v2 decisions (`yaml_v2`)
|
|
72
89
|
|
|
73
90
|
A conversion can carry a YAML v2 decisions document (zone mappings, interface
|
|
@@ -114,17 +131,68 @@ netconverter connect claude-desktop # merge into claude_desktop_config.json
|
|
|
114
131
|
netconverter connect --all # every assistant found on this computer, one prompt each
|
|
115
132
|
netconverter connect chatgpt # ChatGPT / claude.ai: prints remote-connector setup steps
|
|
116
133
|
netconverter mcp --workspace ~/migrations # what an assistant runs; not for interactive use
|
|
117
|
-
netconverter mcp --
|
|
134
|
+
netconverter mcp --level none --workspace ~/migrations # lower this folder's level for one bridge
|
|
135
|
+
netconverter privacy status # this folder's exposure level, what each level shows, recent changes
|
|
136
|
+
netconverter privacy level none # verdicts and counts only (lowering needs no confirmation)
|
|
137
|
+
netconverter privacy level full # raising asks you to type "raise to full" in a terminal
|
|
138
|
+
netconverter privacy level selected --sections nat,routes # masked plus chosen sections
|
|
139
|
+
netconverter privacy apply --client claude-code # deny the client's own file tools this folder (diff, then yes)
|
|
118
140
|
netconverter update --check # is a newer release published? (--json for JSON)
|
|
119
141
|
netconverter update # verify and install it with uv, after a prompt
|
|
120
142
|
netconverter update --yes # same, without the prompt
|
|
121
143
|
```
|
|
122
144
|
|
|
145
|
+
`connect` writes `netconverter mcp --workspace <folder>` with no view flag (0.4.4 wrote `--strict`): the
|
|
146
|
+
folder's exposure level decides what the assistant sees. Run `connect` again to drop an old `--strict`,
|
|
147
|
+
which would hold the assistant at masked after you raise the level.
|
|
148
|
+
|
|
149
|
+
### Exposure levels (`privacy`)
|
|
150
|
+
|
|
151
|
+
`netconverter privacy level LEVEL` sets what assistants connected to this folder may see; the
|
|
152
|
+
setting lives in `.netconverter/privacy.json` and every change is appended to
|
|
153
|
+
`.netconverter/privacy-audit.jsonl` (time, old → new, sections, user, folder, how it was confirmed).
|
|
154
|
+
|
|
155
|
+
| Level | The assistant gets |
|
|
156
|
+
| --- | --- |
|
|
157
|
+
| `none` | Verdicts, statuses, counts and ids only; every other value is removed and non-JSON text is withheld |
|
|
158
|
+
| `masked` (default) | The server's strict view (names as `<name:…>` tokens); addresses masked as `<ip>`/`<cidr>` by the bridge too; the strict tool set |
|
|
159
|
+
| `selected` | `masked`, plus the sections chosen with `--sections`: `interfaces`, `routes`, `policy`, `nat`, `vpn`, `objects`, `management`, `translation` (their summary tools), `unparsed_lines` (`get_evidence section=unparsed_lines`), `target` (`get_job_brief focus=target`, `get_target_config`), `reports` (`fetch` of job ids). Results stay masked; the server serves this level as strict until per-section un-tokenising ships |
|
|
160
|
+
| `full` | Results as the server serves them for your account (the 0.4.x `--full` view) |
|
|
161
|
+
|
|
162
|
+
Secrets (pre-shared keys, SNMP communities, password hashes, passwords) are removed from every
|
|
163
|
+
result at every level. Lowering works from scripts. Raising (a higher level, or adding a section)
|
|
164
|
+
needs the phrase `raise to LEVEL` typed in a terminal; from a pipe, a script or the MCP bridge it is
|
|
165
|
+
refused (exit 1). No MCP tool can read or change the level or its audit log.
|
|
166
|
+
|
|
167
|
+
**Precedence.** (1) The folder's level is the most any bridge for the folder serves. (2) `mcp --level
|
|
168
|
+
LEVEL` (alias `--view`), `--strict` (= masked) or `--full` (= full), else `NETCONVERTER_MCP_VIEW`, can
|
|
169
|
+
only lower it for that process; a flag beats the variable, and asking for more prints how to raise
|
|
170
|
+
the folder's level. (3) `--guided` serves at most masked and refuses `none`. (4) The bridge sends the
|
|
171
|
+
result as `X-NetConverter-View` on every request and the server applies min(your grant, level):
|
|
172
|
+
`none`/`masked`/`selected` as its strict view, `full` as its default view. Lowering the folder's
|
|
173
|
+
level takes effect on a running bridge's next call; a raise needs the assistant to list tools again.
|
|
174
|
+
|
|
175
|
+
`privacy apply --client CLIENT` keeps the client's own file tools out of the folder, so a
|
|
176
|
+
configuration reaches the model only through the bridge: `claude-code` (`Read(//<folder>/**)` and
|
|
177
|
+
`Edit(//<folder>/**)` in `~/.claude/settings.json`), `cursor` (`Read(<folder>/**)` and
|
|
178
|
+
`Write(<folder>/**)` in `~/.cursor/cli-config.json`), `gemini` (a deny policy for its file and shell
|
|
179
|
+
tools in `~/.gemini/policies/netconverter-<id>.toml`). Each shows a diff, applies after `y` (or
|
|
180
|
+
`--yes`), keeps a `.bak` and changes nothing on a second run; `--print` only shows it. `codex`
|
|
181
|
+
(a permission profile with `"<folder>" = "deny"`) and `openclaw` (`tools.deny`,
|
|
182
|
+
`tools.fs.workspaceOnly`, `sandbox.workspaceAccess`) print the settings to add yourself, because
|
|
183
|
+
they change the client's active profile or policy. Start every client outside the folder: one started
|
|
184
|
+
in it or a parent can reach the files through its project tools.
|
|
185
|
+
|
|
123
186
|
`connect` targets: `claude-code` (through `claude mcp add`, user scope; then offers
|
|
124
187
|
a `Read(//<folder>/**)` deny rule in `~/.claude/settings.json`, default yes),
|
|
125
|
-
`claude-desktop`, `cursor`, `vscode` (this folder's `.vscode/mcp.json`), `codex
|
|
126
|
-
`
|
|
127
|
-
|
|
188
|
+
`claude-desktop`, `cursor`, `vscode` (this folder's `.vscode/mcp.json`), `codex` (with
|
|
189
|
+
`env_vars` forwarding the NetConverter variables), `gemini` (Gemini CLI,
|
|
190
|
+
`~/.gemini/settings.json`, with an `env` block of `$NAME` references because Gemini strips
|
|
191
|
+
variables named like KEY/AUTH/CREDENTIAL; trust the folder in Gemini or no MCP server
|
|
192
|
+
starts), `devin` (Devin Desktop, formerly Windsurf, and Devin CLI:
|
|
193
|
+
`~/.config/devin/mcp_config.json`), `windsurf` (legacy Cascade,
|
|
194
|
+
`~/.codeium/windsurf/mcp_config.json`) and `lmstudio` (`~/.lmstudio/mcp.json`). Paths and
|
|
195
|
+
formats per vendor docs: [connect/compatibility.md](connect/compatibility.md).
|
|
128
196
|
`chatgpt` and `claude-ai` only reach remote MCP servers, so `connect` prints the steps
|
|
129
197
|
to add NetConverter's hosted MCP (`https://api.netconverter.ai/mcp/v1`) in that app and
|
|
130
198
|
changes nothing locally; those apps read jobs, results and the knowledge base but cannot
|
|
@@ -147,9 +215,22 @@ delays a command; its result is cached in your user cache folder.
|
|
|
147
215
|
| `submit_file(path, source_vendor, target_vendor?, job_type?, options?)` | `job_id`, `status`, `sha256`, `bytes`. `job_type`: `convert`, `validate`, `optimize`, or `analyze` (= validate). `options` keys (typed; anything else is refused naming it): `selected_device_groups`, `file_name`, `optimization_options` (optimize), and for convert `zone_mapping`, `remove_unused_objects`, `enable_appid`, `app_id_implementation`, `add_security_profiles`, `log_all_rules`, `implicit_deny`, `panos_target_version` / `routing_engine` / `default_profile_group` (Palo Alto targets), `panorama_device_group` / `panorama_template` (Panorama), `pipeline_mode` (pilot keys). On the full API the convert settings travel as a `yaml_v2` decisions document |
|
|
148
216
|
| `job_status(job_id)` | Status, verdict, review flag, progress and stage when sent, reason counts, vendors |
|
|
149
217
|
| `wait_for_job(job_id, timeout_s=45)` | The `job_status` summary plus `waited_s` and `timed_out` (plus `next` when still running: call it again); polls 2 s, ×1.5, up to 15 s apart, at most 600 s. The default stays under the 60 s tool timeout of Codex and OpenClaw; pass a larger `timeout_s` only when the client allows it. Sends MCP progress notifications when the call has a progress token |
|
|
150
|
-
| `account()` | Signed out: `status` (`signed_out`, `keyring_unreachable`), `signed_in: false`, `message`, `client_version`, `update_available`, `latest_version` (not an error). Signed in: `tier`, `job_types`, `rate_limit_per_min`, `daily_quota`, `auth_kind`, `profile`, `client_version`, `update_available`, `latest_version`, `strict_mode` (
|
|
218
|
+
| `account()` | Signed out: `status` (`signed_out`, `keyring_unreachable`), `signed_in: false`, `message`, `client_version`, `update_available`, `latest_version` (not an error). Signed in: `tier`, `job_types`, `rate_limit_per_min`, `daily_quota`, `auth_kind`, `profile`, `client_version`, `update_available`, `latest_version`, `strict_mode` (true below `full`), `exposure_level` and `exposure_sections` (the level in force, see Exposure levels), `view_mode_grant` and `view_clamped` when the server reports them, `view_mode` (the view the server applies to this session, from `get_account`), `strict_enforced_by` (`server` when that view is strict, `client` while the bridge enforces it locally), `credential_source` (`clerk_session`, `api_key_environment`, `api_key_stored` or `none`; the one credential REST and the remote tools share) |
|
|
151
219
|
| `download(job_id, dest_dir=".")` | Saved file names, sizes and SHA-256 |
|
|
152
220
|
|
|
221
|
+
Every local tool declares an `outputSchema` for its `structuredContent` (error results carry
|
|
222
|
+
none). When the assistant advertises form elicitation in `initialize` (Claude Code, Codex, Cursor
|
|
223
|
+
CLI), `submit_file` first asks in the assistant's own dialog: "Upload <path> (<bytes>, SHA-256 …) to
|
|
224
|
+
NetConverter for <job type>?". Accept uploads; Decline or a dismissed dialog sends nothing and the
|
|
225
|
+
tool returns `upload_declined`. Without elicitation, or when the assistant answers the request with
|
|
226
|
+
an error, the upload proceeds after the assistant's own tool approval, as before. The dialog shows
|
|
227
|
+
the path, size and hash only, never the file's text.
|
|
228
|
+
|
|
229
|
+
The bridge also offers two MCP prompts: `guided-migration` (from a file path to a verdict and
|
|
230
|
+
artifacts) and `mapping-review` (optional `job_id`: what was mapped, what needs review, what is
|
|
231
|
+
blocked). Both tell the assistant it will not get configuration content and name the folder's
|
|
232
|
+
exposure level. `--guided` keeps its own prompts (`migration-studio`, `pre-cutover-review`).
|
|
233
|
+
|
|
153
234
|
Remote NetConverter tools are proxied only from a fixed allowlist, and never a
|
|
154
235
|
`submit_*` tool. Default: `compare_against_intent`, `fetch`, `get_account`,
|
|
155
236
|
`get_acl_summary`, `get_critical_object_impact`, `get_dependency_chains`,
|
|
@@ -159,11 +240,12 @@ Remote NetConverter tools are proxied only from a fixed allowlist, and never a
|
|
|
159
240
|
`get_unused_objects`, `get_vpn_summary`, `get_zone_summary`, `kb_explain`,
|
|
160
241
|
`kb_search`, `list_jobs`, `list_objects_with_attribute`, `list_rules_matching`,
|
|
161
242
|
`query_ir`, `search`, `select_job`, `simulate_flow`, `vendor_capability_lookup`.
|
|
162
|
-
|
|
163
|
-
|
|
243
|
+
At levels `none`, `masked` and `selected` (the default is masked; `full` uses the default list):
|
|
244
|
+
`list_jobs`, `select_job`, `get_account`, `search`, `fetch`,
|
|
164
245
|
`kb_search`, `kb_explain`, `vendor_capability_lookup`, `get_job_brief`,
|
|
165
|
-
`get_evidence`, `get_report
|
|
166
|
-
|
|
246
|
+
`get_evidence`, `get_report`, plus the chosen sections' tools under `selected`. A listed tool appears
|
|
247
|
+
only if the server offers it.
|
|
248
|
+
The bridge sends the level on every request (`X-NetConverter-View: none|masked|selected|full`;
|
|
167
249
|
the server may only lower the grant's view, never raise it) and reads the view in force from
|
|
168
250
|
`get_account`. Until the server applies it, the bridge enforces strict locally: it refuses
|
|
169
251
|
`get_evidence section=unparsed_lines`, `get_job_brief focus=target` and any `fetch` that is not
|
|
@@ -175,11 +257,13 @@ Global options go before the subcommand: `netconverter --workspace DIR --server
|
|
|
175
257
|
Environment: `NETCONVERTER_URL`, `NETCONVERTER_PROVIDER`, `NETCONVERTER_MODEL`,
|
|
176
258
|
`NETCONVERTER_AUTH=key` or `=clerk` (force one credential; unset, plain commands use a stored key first, then
|
|
177
259
|
your sign-in, while `mcp` prefers the sign-in and says on stderr which API key it leaves unused;
|
|
178
|
-
`NETCONVERTER_MCP_AUTH` overrides it for `mcp` only), `NETCONVERTER_TRUSTED_HOSTS`, `NETCONVERTER_MCP_VIEW=full` (same as `mcp --
|
|
179
|
-
explicit
|
|
260
|
+
`NETCONVERTER_MCP_AUTH` overrides it for `mcp` only), `NETCONVERTER_TRUSTED_HOSTS`, `NETCONVERTER_MCP_VIEW=none|masked|selected|full|strict` (same as `mcp --level`; it can only lower
|
|
261
|
+
the folder's exposure level, and an explicit flag wins),
|
|
180
262
|
`NETCONVERTER_NO_UPDATE_CHECK=1` (no daily update check or notice; `account` then reports
|
|
181
263
|
`update_available: null`), `NETCONVERTER_KEYRING_TIMEOUT_S` (how long to wait for the OS keyring
|
|
182
|
-
before reporting it locked; default 5)
|
|
264
|
+
before reporting it locked; default 5), `NETCONVERTER_CREDENTIAL_STORE`,
|
|
265
|
+
`NETCONVERTER_CREDENTIAL_PASSPHRASE`, `NETCONVERTER_CREDENTIAL_PASSPHRASE_FILE` and
|
|
266
|
+
`NETCONVERTER_CREDENTIAL_FILE` (the encrypted credential file; see Credentials and profiles).
|
|
183
267
|
Never put a literal key in shell history or a shared script.
|
|
184
268
|
|
|
185
269
|
## Exit codes
|
|
@@ -222,9 +306,10 @@ file is reported as a missing file, never as "not signed in".
|
|
|
222
306
|
| No verified configuration | Read validation reports and warnings; evidence can be available even when no deployable output is produced |
|
|
223
307
|
| Proxy-only network fails | Client HTTP connections ignore environment proxy settings and do not follow redirects; use a network with direct access to configured endpoints |
|
|
224
308
|
| Full-screen UI unsuitable | Use `netconverter plain` or individual CLI commands |
|
|
309
|
+
| "the credentials are in the encrypted file …, which this process cannot open" | Set `NETCONVERTER_CREDENTIAL_PASSPHRASE` (or `NETCONVERTER_CREDENTIAL_PASSPHRASE_FILE`) to the passphrase used at sign-in, in the shell or in the AI client's `env` for the bridge. "does not open" means a wrong passphrase or an altered file |
|
|
225
310
|
| "Your system keyring is locked" (exit 3) | The OS keyring did not answer within 5 seconds (a locked Secret Service collection after a reboot, or a keychain waiting for a password). Unlock it (for example by logging in to the desktop session), or sign in again with `netconverter login` |
|
|
226
311
|
| `keyring_unreachable` from the bridge (Linux) | The assistant launched `netconverter mcp` without `DBUS_SESSION_BUS_ADDRESS`; the bridge tries `$XDG_RUNTIME_DIR/bus` and `/run/user/<uid>/bus`, else set that variable (or `NETCONVERTER_API_KEY`) in the assistant's MCP server environment and restart it |
|
|
227
|
-
| Assistant cannot see a NetConverter tool | The bridge lists only allowlisted remote tools the server offers (fewer
|
|
312
|
+
| Assistant cannot see a NetConverter tool | The bridge lists only allowlisted remote tools the server offers (fewer below `full`; `netconverter privacy status` shows the level); update the client with `netconverter update` |
|
|
228
313
|
| `netconverter update` says uv is not on PATH | Install uv, or follow the printed download, `shasum -a 256 -c SHA256SUMS` and `uv tool install --force` steps |
|
|
229
314
|
|
|
230
315
|
Use the server job ID and client version when asking for help. Do not attach
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
# Privacy and data flow
|
|
2
|
+
|
|
3
|
+
## Two separate connections
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
Selected config + explicit parameters ── HTTPS ──> NetConverter service
|
|
7
|
+
<── job status, reports, verified artifacts
|
|
8
|
+
|
|
9
|
+
Allowlisted operation intent ──> Optional selected model provider
|
|
10
|
+
<── One permitted operation
|
|
11
|
+
|
|
12
|
+
Your AI assistant ── file path ──> netconverter mcp (on this machine) ── HTTPS ──> NetConverter
|
|
13
|
+
<── job id, sha256, byte count, summaries ──
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
With the full API, choosing a file only pins it by SHA-256; the file is sent when
|
|
17
|
+
you choose **Submit** (a pilot key uploads at selection, after its own confirmation).
|
|
18
|
+
|
|
19
|
+
Selecting a file uploads its full contents directly to NetConverter. This is a
|
|
20
|
+
hosted conversion service, not an offline engine. Raw configurations, generated
|
|
21
|
+
configurations, reports, object identifiers, and addresses are excluded from the
|
|
22
|
+
client's automatic model requests. Unknown words in natural-language input become
|
|
23
|
+
fixed opaque references before a provider call; full prompts are not saved as a
|
|
24
|
+
conversation transcript. Detailed results are rendered locally and saved to your
|
|
25
|
+
workspace, not supplied as model context.
|
|
26
|
+
|
|
27
|
+
The same restricted operation schema applies to Anthropic, OpenAI, Gemini, and
|
|
28
|
+
Ollama. Hosted adapters use fixed official endpoints. Ollama uses a loopback
|
|
29
|
+
endpoint, and failure does not trigger a hosted fallback. A loopback connection
|
|
30
|
+
alone does not prove that an independently configured model runtime is offline;
|
|
31
|
+
choose a local model and review that runtime's network settings separately.
|
|
32
|
+
The terminal neither bundles nor downloads model weights.
|
|
33
|
+
|
|
34
|
+
## What your AI assistant can call
|
|
35
|
+
|
|
36
|
+
The bridge offers its local tools (`submit_file`, `job_status`, `wait_for_job`,
|
|
37
|
+
`account`, `download`) and proxies NetConverter's remote tools only from a fixed
|
|
38
|
+
client-side allowlist of read tools. A tool the server adds later is not offered
|
|
39
|
+
until a client release lists it, and a remote tool named `submit_*` is never
|
|
40
|
+
proxied.
|
|
41
|
+
|
|
42
|
+
### Exposure levels
|
|
43
|
+
|
|
44
|
+
You choose how much of a job's results an assistant sees, per workspace folder
|
|
45
|
+
(`netconverter privacy level`, default **masked**):
|
|
46
|
+
|
|
47
|
+
- **none**: verdicts, statuses, counts and ids only. The bridge removes every other value from
|
|
48
|
+
every result and withholds non-JSON text.
|
|
49
|
+
- **masked**: the server's strict view (names arrive as `<name:…>` tokens) and the strict tool set
|
|
50
|
+
(job list and selection, account, search and fetch, knowledge base, vendor capabilities, job
|
|
51
|
+
brief, evidence, report). The bridge also refuses the configuration-content calls
|
|
52
|
+
(`unparsed_lines`, `focus=target`, non-`kb:` fetch) and masks every address as `<ip>`/`<cidr>`.
|
|
53
|
+
Names are tokenised only by the server's strict view, not locally; `account.strict_enforced_by`
|
|
54
|
+
says whether the server or only the bridge is enforcing it.
|
|
55
|
+
- **selected**: masked, plus the sections you chose (`--sections nat,routes`, …), which add their
|
|
56
|
+
summary tools or lift one of those refusals. Results stay masked; the server serves this level as
|
|
57
|
+
its strict view until per-section un-tokenising ships.
|
|
58
|
+
- **full**: the results as the server serves them for your account (0.4.x `--full`).
|
|
59
|
+
|
|
60
|
+
At **every** level the bridge strips secrets client-side: values of keys such as `psk`,
|
|
61
|
+
`password`, `community`, `*_hash`, configuration syntax such as `pre-shared-key X`,
|
|
62
|
+
`snmp-server community X`, `password 7 X`, `secret 5 X`, and crypt/`ENC`/`-AQ==` hashes become
|
|
63
|
+
`<secret>`. This is defence in depth over the server's own view; it is pattern-based and does not
|
|
64
|
+
replace the server's handling.
|
|
65
|
+
|
|
66
|
+
The bridge sends the level as `X-NetConverter-View` on every remote request; the server applies
|
|
67
|
+
min(your grant, the level), so a session can only lower what the tenant's grant allows, and
|
|
68
|
+
`account` reports `exposure_level`, the server's `view_mode` and, when sent, `view_mode_grant`
|
|
69
|
+
and `view_clamped`. The level is re-read on every call, so lowering it takes effect at once.
|
|
70
|
+
|
|
71
|
+
**Raising the level requires typing `raise to LEVEL` in a terminal.** `netconverter privacy level`
|
|
72
|
+
refuses a raise when stdin or stdout is not a terminal, so no script, pipe, MCP tool or model can
|
|
73
|
+
raise it; lowering works anywhere. Every change is appended to
|
|
74
|
+
`.netconverter/privacy-audit.jsonl` (time, old → new, sections, OS user, folder, `tty` or
|
|
75
|
+
`not_needed`). A `privacy.json` above masked without a matching typed raise in that log is ignored
|
|
76
|
+
(the bridge uses masked and says so). The `.netconverter` folder is never a source or destination
|
|
77
|
+
for any bridge tool, so neither file is reachable through MCP.
|
|
78
|
+
|
|
79
|
+
**Flags and precedence.** The folder's level is the ceiling. `netconverter mcp --level LEVEL`,
|
|
80
|
+
`--strict` (= masked), `--full` (= full) or `NETCONVERTER_MCP_VIEW` can only lower it for one bridge
|
|
81
|
+
process (a flag beats the variable); `--full` therefore widens the view only after
|
|
82
|
+
`netconverter privacy level full`. `--guided` serves at most masked and refuses `none`.
|
|
83
|
+
`netconverter connect` writes no view flag (0.4.4 wrote `--strict`; reconnect to drop it).
|
|
84
|
+
**Upgrade note (0.5.0):** an assistant that relied on `--full` now gets masked until you raise the
|
|
85
|
+
folder's level in a terminal.
|
|
86
|
+
|
|
87
|
+
The `account` tool
|
|
88
|
+
returns only tier, job types, rate limit, daily quota, auth kind, credential source,
|
|
89
|
+
exposure level, view mode and client version facts: no tokens, e-mail addresses, key hints or
|
|
90
|
+
tenant IDs. `job_status` and `wait_for_job` (and its progress messages) carry an
|
|
91
|
+
allowlisted status and percentage plus the stage: the server's fixed-vocabulary
|
|
92
|
+
`stage_key` when it sends one, otherwise its progress text made single-line,
|
|
93
|
+
stripped of control characters and capped at 120 characters; a stage that names an
|
|
94
|
+
internal id (for example "Stored to corpus (ID: …)") is reported as `storing`.
|
|
95
|
+
|
|
96
|
+
`submit_file` accepts job `options` only from a fixed, typed allowlist (its schema
|
|
97
|
+
lists every key). The file, vendors, job type, `technology`, and any decisions document
|
|
98
|
+
(`yaml_v2`, `yaml`, `manual_mappings`) can never come from options, and an unknown key
|
|
99
|
+
is refused naming it before anything is uploaded. When the assistant supports form
|
|
100
|
+
elicitation, `submit_file` asks you to confirm the upload in the assistant's own dialog (path,
|
|
101
|
+
size and SHA-256 only) and sends nothing if you decline or dismiss it.
|
|
102
|
+
|
|
103
|
+
### Keep the assistant out of the files
|
|
104
|
+
|
|
105
|
+
The bridge uploads a configuration by **path**: it reads the file itself and sends
|
|
106
|
+
it to NetConverter, so the assistant never needs the file's text. An assistant
|
|
107
|
+
with its own file tools could still open the file and place its contents in the
|
|
108
|
+
model conversation (tester MCP-C4: every client except Claude Desktop can, when the
|
|
109
|
+
folder is in reach). `netconverter privacy apply --client CLIENT` sets the client's own
|
|
110
|
+
deny rules for the folder; it shows a diff, applies only after yes, keeps a `.bak`, and a
|
|
111
|
+
second run changes nothing:
|
|
112
|
+
|
|
113
|
+
- **Claude Code**: `Read(//<folder>/**)` and `Edit(//<folder>/**)` in the user-scope
|
|
114
|
+
`~/.claude/settings.json` `permissions.deny` (`//` is Claude Code's absolute-path form).
|
|
115
|
+
`netconverter connect claude-code` also offers the Read rule (default yes). Its Bash tool is not
|
|
116
|
+
covered: keep it on ask, or add `Bash(cat:*)` yourself (that blocks `cat` everywhere).
|
|
117
|
+
- **Cursor CLI**: `Read(<folder>/**)` and `Write(<folder>/**)` in `~/.cursor/cli-config.json`
|
|
118
|
+
`permissions.deny`; add the folder to the opened project's `.cursorignore` if it sits inside it.
|
|
119
|
+
- **Gemini CLI**: `~/.gemini/policies/netconverter-<id>.toml` denies `read_file`,
|
|
120
|
+
`read_many_files`, `write_file`, `replace`, `glob`, `list_directory`, the search tools and
|
|
121
|
+
`run_shell_command` any argument naming the folder; add it to `.geminiignore` too.
|
|
122
|
+
- **Codex** (printed, not applied): a permission profile with `"<folder>" = "deny"` made active
|
|
123
|
+
by `default_permissions`; it replaces your active sandbox profile, so you add it.
|
|
124
|
+
- **OpenClaw** (printed, not applied): an agent workspace other than the folder,
|
|
125
|
+
`tools.deny: ["read", "exec"]`, `tools.fs.workspaceOnly: true`, `sandbox.workspaceAccess: "none"`.
|
|
126
|
+
|
|
127
|
+
Deny rules also keep the client from reading the reports the bridge downloads into that folder;
|
|
128
|
+
open those yourself. Start each client outside the folder: one started in it or a parent folder
|
|
129
|
+
reaches the files through its project tools. These settings govern the client's own tools; they
|
|
130
|
+
do not stop a shell command you approve, and the tests prove the files written, not each live
|
|
131
|
+
client's enforcement.
|
|
132
|
+
|
|
133
|
+
## Tools and files
|
|
134
|
+
|
|
135
|
+
Models request one allowlisted operation. They receive no shell, unrestricted
|
|
136
|
+
filesystem, arbitrary URL, or arbitrary server endpoint tool. Sensitive values
|
|
137
|
+
such as addresses and object names are entered through structured commands and
|
|
138
|
+
sent directly to NetConverter. Configuration comments and report text are data;
|
|
139
|
+
they are never executed as instructions.
|
|
140
|
+
|
|
141
|
+
The workspace boundary rejects paths and symlinks that escape the chosen folder.
|
|
142
|
+
Output names include the server job ID. Downloads verify the manifest, length,
|
|
143
|
+
and SHA-256 before atomic writes. Identical existing files can be reused;
|
|
144
|
+
differing files are preserved and produce an error. Hash verification detects
|
|
145
|
+
mismatches; it does not replace trust in the server producing the artifacts.
|
|
146
|
+
|
|
147
|
+
## Credentials and local state
|
|
148
|
+
|
|
149
|
+
The supported OS credential store holds API keys and the sign-in when available;
|
|
150
|
+
the client refuses plaintext keyring backends. Without one, they go to the
|
|
151
|
+
passphrase-encrypted credential file below, or, when you give no passphrase, are
|
|
152
|
+
entered for the session and held in memory. On macOS, the Keychain service is `NetConverter Terminal` (kept under that name
|
|
153
|
+
since 0.1.x so saved credentials survive the rename to NetConverter CLI).
|
|
154
|
+
Server accounts are scoped to the server URL; model accounts are provider names.
|
|
155
|
+
Credentials are never written into `.netconverter/`.
|
|
156
|
+
|
|
157
|
+
### Encrypted credential file (headless machines)
|
|
158
|
+
|
|
159
|
+
An SSH host, a container or a server without a desktop session usually has no OS
|
|
160
|
+
credential store (no Secret Service on D-Bus), so a sign-in there used to last only
|
|
161
|
+
for one run. The client can now keep the sign-in, and stored API keys, in an
|
|
162
|
+
**encrypted credential file** instead:
|
|
163
|
+
|
|
164
|
+
| `NETCONVERTER_CREDENTIAL_STORE` | Where new credentials go | Reads |
|
|
165
|
+
| --- | --- | --- |
|
|
166
|
+
| `auto` (default) | The OS credential store when it is available; otherwise the encrypted file | Both |
|
|
167
|
+
| `keyring` | The OS credential store only; never a file | The OS store |
|
|
168
|
+
| `file` | The encrypted file, even when an OS store exists | The file |
|
|
169
|
+
|
|
170
|
+
`netconverter login --store file|keyring|auto` chooses for one sign-in; set the
|
|
171
|
+
variable to keep the choice. `login` prints the store it used
|
|
172
|
+
(`credential_storage`), names it on stderr before a sign-in that goes to the file,
|
|
173
|
+
and `whoami` shows it (`credential_store`).
|
|
174
|
+
|
|
175
|
+
- **Where:** `credentials.enc` in your user config folder
|
|
176
|
+
(`~/.config/netconverter/` on Linux, `~/Library/Application Support/netconverter/`
|
|
177
|
+
on macOS, `%APPDATA%\netconverter\` on Windows), or `NETCONVERTER_CREDENTIAL_FILE`.
|
|
178
|
+
Written atomically with mode `0600` in a `0700` folder.
|
|
179
|
+
- **How:** AES-256-GCM (authenticated encryption) with a key derived from your
|
|
180
|
+
passphrase by scrypt (N=2^15, r=8, p=1, random 16-byte salt), using the pyca
|
|
181
|
+
`cryptography` library. Each write uses a fresh random nonce, the file's header
|
|
182
|
+
is authenticated with the ciphertext, and the entry names are encrypted with the
|
|
183
|
+
values: the file names no account, host or token.
|
|
184
|
+
- **Passphrase:** at least 12 characters, from `NETCONVERTER_CREDENTIAL_PASSPHRASE`,
|
|
185
|
+
from the file named by `NETCONVERTER_CREDENTIAL_PASSPHRASE_FILE` (a Docker or
|
|
186
|
+
Kubernetes secret, a systemd credential), or typed at a hidden prompt on a
|
|
187
|
+
terminal (twice when the file is created). It is never written anywhere by the
|
|
188
|
+
client; the derived key stays in memory for the one process.
|
|
189
|
+
- **AI clients:** the bridge (`netconverter mcp`) cannot prompt, so an assistant
|
|
190
|
+
that starts it needs the passphrase variable in the server's `env`. Without it the
|
|
191
|
+
bridge reports that the credentials are in the encrypted file and which variable
|
|
192
|
+
it needs. There is no way to recover a forgotten passphrase: remove the file and
|
|
193
|
+
sign in again.
|
|
194
|
+
|
|
195
|
+
**What it protects against:** a copy of the file on its own, such as a backup, a
|
|
196
|
+
disk image, a synced or shared home folder, or another local user who can read the file
|
|
197
|
+
despite its mode. Without the passphrase they get ciphertext, and scrypt makes
|
|
198
|
+
guessing a strong passphrase expensive. Tampering is detected and the file is refused.
|
|
199
|
+
|
|
200
|
+
**What it does not protect against:** anyone or anything that can run as you on
|
|
201
|
+
that machine while the passphrase is available. That includes malware in your
|
|
202
|
+
account, an administrator or root, and any process that can read your environment
|
|
203
|
+
or the passphrase file. A passphrase kept in a shell profile or an unprotected file
|
|
204
|
+
beside `credentials.enc` reduces the protection to the file permissions alone. A
|
|
205
|
+
weak passphrase can be guessed offline from a stolen copy. The file does not protect
|
|
206
|
+
tokens in memory while the client runs, and it does not stop a stolen, still-valid
|
|
207
|
+
token from being used: sign out (`netconverter logout --all`) or revoke the key.
|
|
208
|
+
This file is weaker than an OS credential store, which ties secrets to your login
|
|
209
|
+
session and hardware where it can, so `auto` uses the file only when no OS store is
|
|
210
|
+
reachable. Surviving a reboot on a headless host is a tester acceptance step.
|
|
211
|
+
|
|
212
|
+
The workspace contains non-secret connection preferences, filenames, revision
|
|
213
|
+
hashes, job handles, and retry metadata. Some structured conversion decisions can
|
|
214
|
+
also appear in pending-request metadata. These records and downloaded findings
|
|
215
|
+
may still be sensitive. Keep the folder private and out of public repositories.
|
|
216
|
+
The client does not persist a free-text prompt transcript or provider responses.
|
|
217
|
+
The local MCP bridge appends one metadata line per tool call to
|
|
218
|
+
`.netconverter/bridge.jsonl` (time, assistant name, tool, relative path, SHA-256,
|
|
219
|
+
byte count, job id, vendors, status) so the app can show `/activity`. It never
|
|
220
|
+
records configuration text, tool results or credentials, and keeps the newest 500 lines.
|
|
221
|
+
|
|
222
|
+
`netconverter update` and the daily update check contact only the public GitHub
|
|
223
|
+
API for `valeronlabs/netconverter_terminals` (and GitHub's release download hosts),
|
|
224
|
+
with no NetConverter credential. The request carries a `netconverter-cli/<version>`
|
|
225
|
+
User-Agent. The check stores the latest version and check times in
|
|
226
|
+
`update-check.json` in your user cache folder (`~/Library/Caches/netconverter` on
|
|
227
|
+
macOS), never in the workspace. `NETCONVERTER_NO_UPDATE_CHECK=1` turns the daily
|
|
228
|
+
check off; `netconverter mcp` never prints the notice. Its `account` tool reads
|
|
229
|
+
the same cache and, when the cache is more than a day old, makes the same check
|
|
230
|
+
with a 3-second timeout. An update installs only a wheel whose SHA-256
|
|
231
|
+
matches the release's `SHA256SUMS`. Both files come from the same release, so
|
|
232
|
+
this detects a corrupted or swapped download, not a compromised release.
|
|
233
|
+
|
|
234
|
+
Production uses HTTPS with certificate verification. The client rejects plain
|
|
235
|
+
HTTP except explicit loopback addresses for development, ignores environment
|
|
236
|
+
proxy settings, and does not follow redirects. Local downloaded artifacts are
|
|
237
|
+
**ordinary files**; there is no password-encrypted output bundle in this release.
|
|
238
|
+
Use your OS storage protection and organization policy for files at rest.
|
|
239
|
+
|
|
240
|
+
## Verification boundary
|
|
241
|
+
|
|
242
|
+
Automated client tests exercise synthetic canaries, provider payload abstraction,
|
|
243
|
+
forbidden operations, workspace escape attempts, output preservation, and
|
|
244
|
+
interrupted sessions. Every request is tenant-scoped by the credential. A 0.1.x
|
|
245
|
+
Terminal Quick key reaches only its restricted pilot profile; full-API keys and
|
|
246
|
+
Clerk sign-ins reach the External API (`/jobs`, `/capabilities`) and, for questions,
|
|
247
|
+
the read-only NetConverter MCP tools. Full-fidelity server AI stays opt-in per tenant.
|
|
248
|
+
|
|
249
|
+
**The complete audit of backend AI-provider payloads remains open.** Client tests
|
|
250
|
+
and clean diagnostic-log checks do not establish that every downstream server
|
|
251
|
+
provider path has been audited. Use synthetic configurations for initial public
|
|
252
|
+
pilot testing and obtain the relevant backend privacy acceptance before uploading
|
|
253
|
+
sensitive customer configurations. See [verification status](VERIFICATION.md).
|
|
254
|
+
|
|
255
|
+
No client can prevent a user from separately pasting a configuration into another
|
|
256
|
+
AI application. This document describes this client's implemented boundary.
|
|
@@ -4,7 +4,7 @@ NetConverter reaches your AI assistant in one of two ways. Pick the one your ass
|
|
|
4
4
|
|
|
5
5
|
| Way | What your AI can do | Assistants |
|
|
6
6
|
|---|---|---|
|
|
7
|
-
| **Terminal bridge** (`netconverter mcp`, runs on your computer) | Everything below, **plus submit** configurations for conversion, validation and optimization. The bridge uploads the file from disk; the configuration never passes through the model. | Claude Desktop, Claude Code, Cursor, Gemini CLI, Codex CLI, VS Code, Windsurf, LM Studio, OpenClaw |
|
|
7
|
+
| **Terminal bridge** (`netconverter mcp`, runs on your computer) | Everything below, **plus submit** configurations for conversion, validation and optimization. The bridge uploads the file from disk; the configuration never passes through the model. | Claude Desktop, Claude Code, Cursor, Gemini CLI, Codex CLI, VS Code, Devin Desktop / Windsurf, LM Studio, OpenClaw |
|
|
8
8
|
| **Remote connector** (`https://api.netconverter.ai/mcp/v1`) | Read your jobs, verdicts, evidence and reports, your account, and the NetConverter migration knowledge base. No file submission. | claude.ai (web, mobile, Desktop chat), ChatGPT |
|
|
9
9
|
|
|
10
10
|
Both need a NetConverter account with **MCP access enabled** by your administrator
|
|
@@ -17,7 +17,8 @@ Both need a NetConverter account with **MCP access enabled** by your administrat
|
|
|
17
17
|
- [ChatGPT](chatgpt.md) — remote connector
|
|
18
18
|
- [Claude Desktop](claude-desktop.md) — terminal bridge
|
|
19
19
|
- [Claude Code](claude-code.md) — terminal bridge
|
|
20
|
-
- [Cursor, Gemini CLI, Codex CLI, VS Code, Windsurf, LM Studio](other-assistants.md) — terminal bridge
|
|
20
|
+
- [Cursor, Gemini CLI, Codex CLI, VS Code, Devin Desktop / Windsurf, LM Studio](other-assistants.md) — terminal bridge
|
|
21
|
+
- [Compatibility matrix](compatibility.md): each client's config path and format, the vendor doc checked, and live-test status
|
|
21
22
|
- [OpenClaw](openclaw.md) — terminal bridge, through `openclaw mcp`
|
|
22
23
|
|
|
23
24
|
## Fastest path (terminal bridge)
|