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.
Files changed (128) hide show
  1. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/CHANGELOG.md +47 -0
  2. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/PKG-INFO +14 -9
  3. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/README.md +12 -8
  4. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/COMMANDS.md +98 -13
  5. netconverter_cli-0.6.0/docs/PRIVACY.md +256 -0
  6. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/README.md +3 -2
  7. netconverter_cli-0.6.0/docs/connect/compatibility.md +42 -0
  8. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/openclaw.md +4 -3
  9. netconverter_cli-0.6.0/docs/connect/other-assistants.md +47 -0
  10. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/pyproject.toml +3 -2
  11. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/__init__.py +1 -1
  12. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/clerk.py +19 -9
  13. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/cli.py +73 -20
  14. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/connect.py +68 -17
  15. netconverter_cli-0.6.0/src/netconverter_cli/credential_file.py +311 -0
  16. netconverter_cli-0.6.0/src/netconverter_cli/credentials.py +373 -0
  17. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/drafts.py +16 -8
  18. netconverter_cli-0.6.0/src/netconverter_cli/exposure.py +392 -0
  19. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/guided.py +41 -7
  20. netconverter_cli-0.6.0/src/netconverter_cli/mcp_client_features.py +212 -0
  21. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/mcp_server.py +209 -18
  22. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/mcp_workflows.py +2 -2
  23. netconverter_cli-0.6.0/src/netconverter_cli/privacy_apply.py +248 -0
  24. netconverter_cli-0.6.0/src/netconverter_cli/privacy_cli.py +104 -0
  25. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/remote_mcp.py +41 -2
  26. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/conftest.py +8 -0
  27. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_cli_020.py +4 -2
  28. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_connect_030.py +1 -1
  29. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_connect_031.py +1 -1
  30. netconverter_cli-0.6.0/tests/test_connect_compat_014.py +97 -0
  31. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_connect_openclaw_014.py +6 -6
  32. netconverter_cli-0.6.0/tests/test_credential_file_010.py +274 -0
  33. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_drafts.py +28 -1
  34. netconverter_cli-0.6.0/tests/test_exposure_levels_013.py +301 -0
  35. netconverter_cli-0.6.0/tests/test_guided_full_api_019.py +194 -0
  36. netconverter_cli-0.6.0/tests/test_guided_mapping_012.py +128 -0
  37. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_mcp.py +7 -6
  38. netconverter_cli-0.6.0/tests/test_mcp_features_020.py +243 -0
  39. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_mcp_workflows.py +1 -1
  40. netconverter_cli-0.6.0/tests/test_privacy_apply_013.py +145 -0
  41. netconverter_cli-0.6.0/tests/test_privacy_cli_013.py +152 -0
  42. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_strict_default_011.py +24 -16
  43. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_strict_view_015.py +15 -9
  44. netconverter_cli-0.4.4/docs/PRIVACY.md +0 -148
  45. netconverter_cli-0.4.4/docs/connect/other-assistants.md +0 -32
  46. netconverter_cli-0.4.4/src/netconverter_cli/credentials.py +0 -216
  47. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/.gitignore +0 -0
  48. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/LICENSE +0 -0
  49. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/QUICK_START.md +0 -0
  50. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/SECURITY.md +0 -0
  51. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/RELEASING.md +0 -0
  52. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/VERIFICATION.md +0 -0
  53. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/chatgpt.md +0 -0
  54. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/claude-ai.md +0 -0
  55. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/claude-code.md +0 -0
  56. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/claude-desktop.md +0 -0
  57. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/connect/getting-access.md +0 -0
  58. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/docs/guided-workflows.md +0 -0
  59. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/examples/README.md +0 -0
  60. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/activity.py +0 -0
  61. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/api.py +0 -0
  62. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/backend.py +0 -0
  63. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/branding.py +0 -0
  64. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/catalog.py +0 -0
  65. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/commands.py +0 -0
  66. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/connect_openclaw.py +0 -0
  67. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/controller.py +0 -0
  68. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/design_catalog.py +0 -0
  69. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/draft_cli.py +0 -0
  70. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/draft_io.py +0 -0
  71. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/errors.py +0 -0
  72. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/guided_operations.json +0 -0
  73. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/guided_projects.json +0 -0
  74. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/job_options.py +0 -0
  75. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/license.py +0 -0
  76. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/one_shot.py +0 -0
  77. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/palette.py +0 -0
  78. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/presentation.py +0 -0
  79. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/privacy.py +0 -0
  80. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/project_cli.py +0 -0
  81. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/projects.py +0 -0
  82. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/providers.py +0 -0
  83. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/setup.py +0 -0
  84. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/summary.py +0 -0
  85. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/tui.py +0 -0
  86. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/update.py +0 -0
  87. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/walkthrough.py +0 -0
  88. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/windows_draft_io.py +0 -0
  89. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/src/netconverter_cli/workspace.py +0 -0
  90. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/fixtures/jobs/opt_4056e02e5b66.json +0 -0
  91. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/fixtures/jobs/tra_4058ef406cd6.json +0 -0
  92. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/fixtures/jobs/tra_running.json +0 -0
  93. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/fixtures/jobs/val_9f9acb9b5a59.json +0 -0
  94. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/fixtures/jobs/val_9f9acb9b5a59.sarif +0 -0
  95. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_autodetect_v5.py +0 -0
  96. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_boundaries.py +0 -0
  97. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_bridge_polish_021.py +0 -0
  98. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_clerk.py +0 -0
  99. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_clerk_host_binding.py +0 -0
  100. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_connect_direct_entry.py +0 -0
  101. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_download_analysis.py +0 -0
  102. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_draft_cli.py +0 -0
  103. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_draft_io.py +0 -0
  104. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_draft_jobs.py +0 -0
  105. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_errors_009.py +0 -0
  106. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_folders_cd_ls.py +0 -0
  107. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_help_008.py +0 -0
  108. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_inline.py +0 -0
  109. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_keyring_bus_017.py +0 -0
  110. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_keyring_timeout_010.py +0 -0
  111. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_license.py +0 -0
  112. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_mcp_auth_016.py +0 -0
  113. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_mcp_jobs.py +0 -0
  114. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_options_011_019.py +0 -0
  115. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_polish_028.py +0 -0
  116. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_presentation.py +0 -0
  117. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_projects.py +0 -0
  118. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_protocols.py +0 -0
  119. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_readonly_workspace.py +0 -0
  120. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_sessions.py +0 -0
  121. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_setup.py +0 -0
  122. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_signin_default.py +0 -0
  123. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_stage_029.py +0 -0
  124. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_summary_007.py +0 -0
  125. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_update.py +0 -0
  126. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_vendor_error_022.py +0 -0
  127. {netconverter_cli-0.4.4 → netconverter_cli-0.6.0}/tests/test_walkthrough.py +0 -0
  128. {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.4.4
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.4.4 ● Server ◆ Bridge claude-code · 2m ago
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). The bridge serves the **strict view** by default (summaries, names as
147
- tokens, no configuration content); `netconverter mcp --full` offers the wider set, and
148
- `connect` writes `--strict` for every assistant. Job `options` from an assistant pass an
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:** if your assistant relied on the wider default view, add
153
- `--full` to its `netconverter mcp` command (or set `NETCONVERTER_MCP_VIEW=full` where it
154
- starts the bridge).
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.4.4 ● Server ◆ Bridge claude-code · 2m ago
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). The bridge serves the **strict view** by default (summaries, names as
113
- tokens, no configuration content); `netconverter mcp --full` offers the wider set, and
114
- `connect` writes `--strict` for every assistant. Job `options` from an assistant pass an
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:** if your assistant relied on the wider default view, add
119
- `--full` to its `netconverter mcp` command (or set `NETCONVERTER_MCP_VIEW=full` where it
120
- starts the bridge).
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 --full --workspace ~/migrations # the wider view (strict is the default)
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
- `gemini` (Gemini CLI, `~/.gemini/settings.json`), `windsurf`
127
- (`~/.codeium/windsurf/mcp_config.json`) and `lmstudio` (`~/.lmstudio/mcp.json`).
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` (the `--strict` flag), `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) |
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
- With the strict view (the default since 0.5.0; `--strict` names it explicitly, `--full` or
163
- `--view full` opts out): `list_jobs`, `select_job`, `get_account`, `search`, `fetch`,
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`. A listed tool appears only if the server offers it.
166
- The strict view also asks the server for its strict view on every request (`X-NetConverter-View: strict`;
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 --full`; strict is the default, and an
179
- explicit `--strict` wins),
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 with `--strict`); update the client with `netconverter update` |
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)