netconverter-cli 0.6.0__tar.gz → 0.7.1__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.6.0 → netconverter_cli-0.7.1}/CHANGELOG.md +33 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/PKG-INFO +49 -4
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/QUICK_START.md +17 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/README.md +48 -3
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/COMMANDS.md +45 -8
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/README.md +2 -2
- netconverter_cli-0.7.1/docs/connect/chatgpt.md +63 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/pyproject.toml +1 -1
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/__init__.py +1 -1
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/api.py +19 -1
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/catalog.py +2 -1
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/cli.py +13 -2
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/connect.py +6 -1
- netconverter_cli-0.7.1/src/netconverter_cli/diagrams.py +67 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/job_options.py +1 -1
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/mcp_client_features.py +35 -4
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/mcp_server.py +271 -47
- netconverter_cli-0.7.1/tests/test_diagrams.py +205 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_guided_mapping_012.py +3 -1
- netconverter_cli-0.7.1/tests/test_guided_prescan_037.py +316 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_mcp.py +10 -5
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_mcp_features_020.py +17 -4
- netconverter_cli-0.6.0/docs/connect/chatgpt.md +0 -22
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/.gitignore +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/LICENSE +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/SECURITY.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/PRIVACY.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/RELEASING.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/VERIFICATION.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/claude-ai.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/claude-code.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/claude-desktop.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/compatibility.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/getting-access.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/openclaw.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/other-assistants.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/guided-workflows.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/examples/README.md +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/activity.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/backend.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/branding.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/clerk.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/commands.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/connect_openclaw.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/controller.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/credential_file.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/credentials.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/design_catalog.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/draft_cli.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/draft_io.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/drafts.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/errors.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/exposure.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/guided.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/guided_operations.json +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/guided_projects.json +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/license.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/mcp_workflows.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/one_shot.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/palette.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/presentation.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/privacy.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/privacy_apply.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/privacy_cli.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/project_cli.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/projects.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/providers.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/remote_mcp.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/setup.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/summary.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/tui.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/update.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/walkthrough.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/windows_draft_io.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/workspace.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/conftest.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/fixtures/jobs/opt_4056e02e5b66.json +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/fixtures/jobs/tra_4058ef406cd6.json +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/fixtures/jobs/tra_running.json +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/fixtures/jobs/val_9f9acb9b5a59.json +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/fixtures/jobs/val_9f9acb9b5a59.sarif +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_autodetect_v5.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_boundaries.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_bridge_polish_021.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_clerk.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_clerk_host_binding.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_cli_020.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_connect_030.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_connect_031.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_connect_compat_014.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_connect_direct_entry.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_connect_openclaw_014.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_credential_file_010.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_download_analysis.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_draft_cli.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_draft_io.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_draft_jobs.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_drafts.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_errors_009.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_exposure_levels_013.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_folders_cd_ls.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_guided_full_api_019.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_help_008.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_inline.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_keyring_bus_017.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_keyring_timeout_010.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_license.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_mcp_auth_016.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_mcp_jobs.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_mcp_workflows.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_options_011_019.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_polish_028.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_presentation.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_privacy_apply_013.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_privacy_cli_013.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_projects.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_protocols.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_readonly_workspace.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_sessions.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_setup.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_signin_default.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_stage_029.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_strict_default_011.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_strict_view_015.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_summary_007.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_update.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_vendor_error_022.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_walkthrough.py +0 -0
- {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_windows_draft_io.py +0 -0
|
@@ -1,5 +1,38 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.7.1 — 2026-11-02
|
|
4
|
+
|
|
5
|
+
- Proxy governed `get_diagram` discovery for selected jobs in full and strict views.
|
|
6
|
+
- `download` accepts an artifact request recipe for SVG, PNG, PDF, draw.io or JSON.
|
|
7
|
+
It uses a fixed authenticated endpoint, checks the expected SHA-256 before an
|
|
8
|
+
atomic write, preserves earlier document revisions, and respects strict view.
|
|
9
|
+
- Explicit `preview_diagram` returns a verified PNG as native MCP image content for
|
|
10
|
+
IDE chat. Streaming, byte and canvas bounds apply; masked/selected force strict
|
|
11
|
+
view and none refuses previews. Automatic summaries and downloads remain metadata only.
|
|
12
|
+
- Availability requires the matching server release; live two-client and public
|
|
13
|
+
package qualification remain separate from synthetic bridge tests.
|
|
14
|
+
|
|
15
|
+
## 0.7.0 — 2026-11-02
|
|
16
|
+
|
|
17
|
+
- New: guided migration from your AI assistant (devnexthop/aws-netconverter.ai#1090).
|
|
18
|
+
`submit_file(..., job_type="prescan")` uploads the file and stops at a `psc_` prescan
|
|
19
|
+
(`target_vendor` optional); the result names the next steps. The bridge now proxies
|
|
20
|
+
`list_operations`, `get_decision_document`, `validate_decision_document`,
|
|
21
|
+
`propose_operations` and `submit_conversion` (the one remote `submit_*` it allows: a prescan
|
|
22
|
+
id and a revision, no configuration text). They need exposure level `full`; the two write
|
|
23
|
+
tools appear only where the server enables them for the tenant, and the server gates and
|
|
24
|
+
audits each call. `submit_conversion` asks for confirmation like an upload. Also proxied at
|
|
25
|
+
`full`: `set_view_level` (it can only lower the server's view for the session).
|
|
26
|
+
- New: `account` reports `guided_migration` (the guided tools this session lists, or the fix
|
|
27
|
+
when the level hides them), and the remote `get_account` carries the same note below `full`.
|
|
28
|
+
- Fix (#37): assistants that advertise forms but decline without showing them (ChatGPT, Claude
|
|
29
|
+
Code) no longer block every upload. A decline within 1.5 s returns `confirmation_required`
|
|
30
|
+
with a single-use `confirm_token` for that exact call: the assistant asks you in the
|
|
31
|
+
conversation and retries with it; no more forms are sent in that session. Declines now carry
|
|
32
|
+
`reason` (`user_declined`, `form_dismissed`, `client_declined_form`). New
|
|
33
|
+
`netconverter mcp --no-upload-confirm` / `NETCONVERTER_MCP_UPLOAD_CONFIRM=0` turns the forms
|
|
34
|
+
off and relies on the assistant's own tool approval.
|
|
35
|
+
|
|
3
36
|
## 0.6.0 — 2026-10-30
|
|
4
37
|
|
|
5
38
|
- Guided drafts retain the server-advertised ASA target format (Palo Alto SET,
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: netconverter-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.7.1
|
|
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
|
|
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
|
|
|
42
42
|
NetConverter — by ValeronLabs LLC.
|
|
43
43
|
|
|
44
44
|
```text
|
|
45
|
-
◆ NetConverter v0.
|
|
45
|
+
◆ NetConverter v0.7.1 ● Server ◆ Bridge claude-code · 2m ago
|
|
46
46
|
▍ Start
|
|
47
47
|
▍ /convert Migrate a configuration to another vendor
|
|
48
48
|
▍ /validate Check a configuration before migrating
|
|
@@ -142,9 +142,18 @@ works on your configurations only through the bridge.
|
|
|
142
142
|
Then ask your assistant, for example: *"Validate edge-fw.conf and tell me what it finds,"*
|
|
143
143
|
*"Convert it to Palo Alto XML,"* *"Can WEB reach DB on tcp/1433?"*
|
|
144
144
|
|
|
145
|
+
**Guided migration:** *"Prescan edge-fw.conf for Palo Alto XML and walk me through the decisions."*
|
|
146
|
+
`submit_file(..., job_type="prescan")` stops at a `psc_` prescan; the assistant reads the decisions
|
|
147
|
+
(`list_operations`, `get_decision_document`, `validate_decision_document`), records your choices
|
|
148
|
+
(`propose_operations`) and, with your OK, queues the conversion (`submit_conversion`). These tools
|
|
149
|
+
need the folder at `netconverter privacy level full`; the two write tools also need them enabled
|
|
150
|
+
for your tenant (docs/COMMANDS.md § Guided migration). If your assistant declines the upload
|
|
151
|
+
confirmation without showing it (ChatGPT, Claude Code), approve in the conversation or run the
|
|
152
|
+
bridge with `--no-upload-confirm`.
|
|
153
|
+
|
|
145
154
|
Bridge tools: `submit_file`, `job_status`, `wait_for_job`, `account`, `download`,
|
|
146
|
-
plus an allowlist of NetConverter's
|
|
147
|
-
|
|
155
|
+
plus an allowlist of NetConverter's tools (reports, evidence, NAT, flows, knowledge base,
|
|
156
|
+
guided mapping and guided migration). What the assistant sees is this folder's **exposure level**
|
|
148
157
|
(`netconverter privacy level none|masked|selected|full`, default **masked**: the strict view,
|
|
149
158
|
names as tokens, addresses masked, no configuration content); secrets are removed at every
|
|
150
159
|
level, and raising the level needs a confirmation typed in a terminal (docs/PRIVACY.md).
|
|
@@ -161,6 +170,42 @@ hold the assistant at masked.
|
|
|
161
170
|
Inside the app, `/activity` and the header's **Bridge** pill show what your AI did
|
|
162
171
|
through the bridge — paths, sizes, SHA-256 and job IDs only.
|
|
163
172
|
|
|
173
|
+
### Show a diagram in IDE chat
|
|
174
|
+
|
|
175
|
+
With the matching diagram-enabled server and bridge, use this prompt in your IDE:
|
|
176
|
+
|
|
177
|
+
> For my selected completed NetConverter job, show its topology diagram here in chat.
|
|
178
|
+
> Call get_diagram, then pass the returned PNG artifact request unchanged to
|
|
179
|
+
> preview_diagram with that job_id. Use the current privacy view. Do not open a local
|
|
180
|
+
> file or fetch an image URL. If preview is refused, report the reason.
|
|
181
|
+
|
|
182
|
+
`preview_diagram` returns an MCP `image` content block (`mimeType: image/png`, base64
|
|
183
|
+
`data`) plus a text/structured receipt with SHA-256, byte count, dimensions and view.
|
|
184
|
+
An IDE that renders MCP image content can display it inline; rendering in individual
|
|
185
|
+
IDE clients still needs live qualification. The bridge fetches from the fixed,
|
|
186
|
+
authenticated NetConverter endpoint, verifies the recipe's SHA-256, and saves no image
|
|
187
|
+
file. It accepts PNG only, at most **2 MiB**, **4096 pixels per side** and **8 million
|
|
188
|
+
pixels**. Use `download` for larger diagrams or SVG/PDF/draw.io/JSON files.
|
|
189
|
+
|
|
190
|
+
Masked and selected levels force the server's strict projection; `none` refuses image
|
|
191
|
+
previews. A stale hash or a hash from another privacy view is refused: request a fresh
|
|
192
|
+
PNG recipe from `get_diagram`. Quick API credentials and development guided mode do
|
|
193
|
+
not provide this preview tool's workflow. Automatic job summaries and ordinary
|
|
194
|
+
downloads continue returning metadata only.
|
|
195
|
+
|
|
196
|
+
For a synthetic protocol check from the source checkout:
|
|
197
|
+
|
|
198
|
+
```sh
|
|
199
|
+
uv run pytest tests/test_diagrams.py -q
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
The preview test exchanges initialize/list/call messages over serialized stdio for
|
|
203
|
+
all supported protocol versions, decodes the returned PNG, and checks hash, privacy,
|
|
204
|
+
size and invalid-input refusals. For an IDE acceptance check, run the prompt above on
|
|
205
|
+
a synthetic completed job and confirm an inline image, a matching receipt hash, and
|
|
206
|
+
no local image-file read or arbitrary-URL request. Synthetic tests alone do not prove
|
|
207
|
+
live server support or a client's inline rendering.
|
|
208
|
+
|
|
164
209
|
## Stay current
|
|
165
210
|
|
|
166
211
|
`netconverter update` upgrades a PyPI install with `uv tool upgrade netconverter-cli`;
|
|
@@ -126,3 +126,20 @@ size, SHA-256 and job ID — never content.
|
|
|
126
126
|
removes the saved sign-in and key.
|
|
127
127
|
|
|
128
128
|
Something failed? See [troubleshooting](docs/COMMANDS.md#troubleshooting).
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
## Branded diagrams (matching server capability required)
|
|
132
|
+
|
|
133
|
+
After selecting a completed job, call `get_diagram` with `kind` set to
|
|
134
|
+
`topology`, `comparison`, `traffic`, `nat` or `policy`. The response describes
|
|
135
|
+
coverage and provides small artifact descriptors. Choose a descriptor and pass
|
|
136
|
+
its `request` object as `diagram` to the local `download` tool, along with the
|
|
137
|
+
job ID and optional workspace destination. Do not pass its URL.
|
|
138
|
+
|
|
139
|
+
The bridge verifies the server-provided SHA-256 and writes only into the
|
|
140
|
+
workspace. It returns file names and hashes, never image bytes. If source,
|
|
141
|
+
renderer or privacy view changed, request a new descriptor. Strict view cannot
|
|
142
|
+
be widened by a download recipe. Missing target/flow evidence stays explicit.
|
|
143
|
+
Editable draw.io files are documentation; editing them changes no configuration
|
|
144
|
+
or validation result. Guided draft and restricted Quick credentials retain their
|
|
145
|
+
existing artifact flows; this request uses completed jobs on the full API.
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
NetConverter — by ValeronLabs LLC.
|
|
8
8
|
|
|
9
9
|
```text
|
|
10
|
-
◆ NetConverter v0.
|
|
10
|
+
◆ NetConverter v0.7.1 ● 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
|
|
@@ -107,9 +107,18 @@ works on your configurations only through the bridge.
|
|
|
107
107
|
Then ask your assistant, for example: *"Validate edge-fw.conf and tell me what it finds,"*
|
|
108
108
|
*"Convert it to Palo Alto XML,"* *"Can WEB reach DB on tcp/1433?"*
|
|
109
109
|
|
|
110
|
+
**Guided migration:** *"Prescan edge-fw.conf for Palo Alto XML and walk me through the decisions."*
|
|
111
|
+
`submit_file(..., job_type="prescan")` stops at a `psc_` prescan; the assistant reads the decisions
|
|
112
|
+
(`list_operations`, `get_decision_document`, `validate_decision_document`), records your choices
|
|
113
|
+
(`propose_operations`) and, with your OK, queues the conversion (`submit_conversion`). These tools
|
|
114
|
+
need the folder at `netconverter privacy level full`; the two write tools also need them enabled
|
|
115
|
+
for your tenant (docs/COMMANDS.md § Guided migration). If your assistant declines the upload
|
|
116
|
+
confirmation without showing it (ChatGPT, Claude Code), approve in the conversation or run the
|
|
117
|
+
bridge with `--no-upload-confirm`.
|
|
118
|
+
|
|
110
119
|
Bridge tools: `submit_file`, `job_status`, `wait_for_job`, `account`, `download`,
|
|
111
|
-
plus an allowlist of NetConverter's
|
|
112
|
-
|
|
120
|
+
plus an allowlist of NetConverter's tools (reports, evidence, NAT, flows, knowledge base,
|
|
121
|
+
guided mapping and guided migration). What the assistant sees is this folder's **exposure level**
|
|
113
122
|
(`netconverter privacy level none|masked|selected|full`, default **masked**: the strict view,
|
|
114
123
|
names as tokens, addresses masked, no configuration content); secrets are removed at every
|
|
115
124
|
level, and raising the level needs a confirmation typed in a terminal (docs/PRIVACY.md).
|
|
@@ -126,6 +135,42 @@ hold the assistant at masked.
|
|
|
126
135
|
Inside the app, `/activity` and the header's **Bridge** pill show what your AI did
|
|
127
136
|
through the bridge — paths, sizes, SHA-256 and job IDs only.
|
|
128
137
|
|
|
138
|
+
### Show a diagram in IDE chat
|
|
139
|
+
|
|
140
|
+
With the matching diagram-enabled server and bridge, use this prompt in your IDE:
|
|
141
|
+
|
|
142
|
+
> For my selected completed NetConverter job, show its topology diagram here in chat.
|
|
143
|
+
> Call get_diagram, then pass the returned PNG artifact request unchanged to
|
|
144
|
+
> preview_diagram with that job_id. Use the current privacy view. Do not open a local
|
|
145
|
+
> file or fetch an image URL. If preview is refused, report the reason.
|
|
146
|
+
|
|
147
|
+
`preview_diagram` returns an MCP `image` content block (`mimeType: image/png`, base64
|
|
148
|
+
`data`) plus a text/structured receipt with SHA-256, byte count, dimensions and view.
|
|
149
|
+
An IDE that renders MCP image content can display it inline; rendering in individual
|
|
150
|
+
IDE clients still needs live qualification. The bridge fetches from the fixed,
|
|
151
|
+
authenticated NetConverter endpoint, verifies the recipe's SHA-256, and saves no image
|
|
152
|
+
file. It accepts PNG only, at most **2 MiB**, **4096 pixels per side** and **8 million
|
|
153
|
+
pixels**. Use `download` for larger diagrams or SVG/PDF/draw.io/JSON files.
|
|
154
|
+
|
|
155
|
+
Masked and selected levels force the server's strict projection; `none` refuses image
|
|
156
|
+
previews. A stale hash or a hash from another privacy view is refused: request a fresh
|
|
157
|
+
PNG recipe from `get_diagram`. Quick API credentials and development guided mode do
|
|
158
|
+
not provide this preview tool's workflow. Automatic job summaries and ordinary
|
|
159
|
+
downloads continue returning metadata only.
|
|
160
|
+
|
|
161
|
+
For a synthetic protocol check from the source checkout:
|
|
162
|
+
|
|
163
|
+
```sh
|
|
164
|
+
uv run pytest tests/test_diagrams.py -q
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
The preview test exchanges initialize/list/call messages over serialized stdio for
|
|
168
|
+
all supported protocol versions, decodes the returned PNG, and checks hash, privacy,
|
|
169
|
+
size and invalid-input refusals. For an IDE acceptance check, run the prompt above on
|
|
170
|
+
a synthetic completed job and confirm an inline image, a matching receipt hash, and
|
|
171
|
+
no local image-file read or arbitrary-URL request. Synthetic tests alone do not prove
|
|
172
|
+
live server support or a client's inline rendering.
|
|
173
|
+
|
|
129
174
|
## Stay current
|
|
130
175
|
|
|
131
176
|
`netconverter update` upgrades a PyPI install with `uv tool upgrade netconverter-cli`;
|
|
@@ -132,6 +132,7 @@ netconverter connect --all # every assistant found on this compute
|
|
|
132
132
|
netconverter connect chatgpt # ChatGPT / claude.ai: prints remote-connector setup steps
|
|
133
133
|
netconverter mcp --workspace ~/migrations # what an assistant runs; not for interactive use
|
|
134
134
|
netconverter mcp --level none --workspace ~/migrations # lower this folder's level for one bridge
|
|
135
|
+
netconverter mcp --no-upload-confirm --workspace ~/migrations # no confirmation forms (ChatGPT, Claude Code)
|
|
135
136
|
netconverter privacy status # this folder's exposure level, what each level shows, recent changes
|
|
136
137
|
netconverter privacy level none # verdicts and counts only (lowering needs no confirmation)
|
|
137
138
|
netconverter privacy level full # raising asks you to type "raise to full" in a terminal
|
|
@@ -212,38 +213,71 @@ delays a command; its result is cached in your user cache folder.
|
|
|
212
213
|
|
|
213
214
|
| Tool | Returns |
|
|
214
215
|
| --- | --- |
|
|
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 |
|
|
216
|
+
| `submit_file(path, source_vendor, target_vendor?, job_type?, options?, confirm_token?)` | `job_id`, `status`, `sha256`, `bytes`. `job_type`: `convert`, `validate`, `optimize`, `prescan`, or `analyze` (= validate). `prescan` starts a guided migration: the job stops at a `psc_` prescan for your decisions (`target_vendor` optional; only `file_name` as an option) and the result adds `job_type`, `next_steps` and `guided_tools` (see Guided migration below). `confirm_token` only after a `confirmation_required` error. `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 |
|
|
216
217
|
| `job_status(job_id)` | Status, verdict, review flag, progress and stage when sent, reason counts, vendors |
|
|
217
218
|
| `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 |
|
|
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) |
|
|
219
|
+
| `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), `guided_migration` (full API: `tools` the session lists, and `hidden_by_level` with the `fix` when the level hides them, or a `note` naming the write tools the server does not list for this account), `credential_source` (`clerk_session`, `api_key_environment`, `api_key_stored` or `none`; the one credential REST and the remote tools share) |
|
|
219
220
|
| `download(job_id, dest_dir=".")` | Saved file names, sizes and SHA-256 |
|
|
220
221
|
|
|
221
222
|
Every local tool declares an `outputSchema` for its `structuredContent` (error results carry
|
|
222
223
|
none). When the assistant advertises form elicitation in `initialize` (Claude Code, Codex, Cursor
|
|
223
224
|
CLI), `submit_file` first asks in the assistant's own dialog: "Upload <path> (<bytes>, SHA-256 …) to
|
|
224
225
|
NetConverter for <job type>?". Accept uploads; Decline or a dismissed dialog sends nothing and the
|
|
225
|
-
tool returns `upload_declined
|
|
226
|
-
an error, the upload proceeds after the assistant's
|
|
227
|
-
the path, size and hash only, never the file's text.
|
|
226
|
+
tool returns `upload_declined` (`reason`: `user_declined` or `form_dismissed`). Without elicitation,
|
|
227
|
+
or when the assistant answers the request with an error, the upload proceeds after the assistant's
|
|
228
|
+
own tool approval, as before. The dialog shows the path, size and hash only, never the file's text.
|
|
229
|
+
`apply_mapping_answers` and `submit_conversion` ask the same way before a conversion is queued
|
|
230
|
+
(`apply_declined`).
|
|
231
|
+
|
|
232
|
+
Some assistants (ChatGPT, Claude Code) advertise form elicitation but decline without showing the
|
|
233
|
+
form. A decline or dismissal that comes back within 1.5 seconds is treated as the client's, not
|
|
234
|
+
yours: nothing is sent, the tool returns `confirmation_required` (`reason: client_declined_form`)
|
|
235
|
+
with a single-use `confirm_token` bound to that exact call (10 minutes), and the bridge sends no
|
|
236
|
+
more forms in that session. The assistant asks you in the conversation; only on your yes does it
|
|
237
|
+
repeat the call with `confirm_token`. To skip forms entirely and rely on the assistant's own tool
|
|
238
|
+
approval, start the bridge with `netconverter mcp --no-upload-confirm` (or set
|
|
239
|
+
`NETCONVERTER_MCP_UPLOAD_CONFIRM=0` in the assistant's MCP server environment).
|
|
228
240
|
|
|
229
241
|
The bridge also offers two MCP prompts: `guided-migration` (from a file path to a verdict and
|
|
230
242
|
artifacts) and `mapping-review` (optional `job_id`: what was mapped, what needs review, what is
|
|
231
243
|
blocked). Both tell the assistant it will not get configuration content and name the folder's
|
|
232
244
|
exposure level. `--guided` keeps its own prompts (`migration-studio`, `pre-cutover-review`).
|
|
233
245
|
|
|
246
|
+
### Guided migration (prescan → decisions → conversion)
|
|
247
|
+
|
|
248
|
+
1. `submit_file(path, source_vendor, target_vendor?, job_type="prescan")` uploads the file and
|
|
249
|
+
returns a `psc_` job id; nothing is converted yet. `wait_for_job` until it is completed.
|
|
250
|
+
2. `list_operations`, `get_decision_document` and `validate_decision_document` with
|
|
251
|
+
`job_id=psc_…` read the decisions the prescan found.
|
|
252
|
+
3. With your OK, `propose_operations(job_id, changes, base_sha256)` records each choice as a new
|
|
253
|
+
revision, and `submit_conversion(job_id, revision)` queues the conversion (confirmed like an
|
|
254
|
+
upload); it answers with the new `tra_` job id. `wait_for_job` and `download` as usual.
|
|
255
|
+
|
|
256
|
+
The guided tools are in the default list only, so they need exposure level `full`:
|
|
257
|
+
run `netconverter privacy level full` in a terminal in the folder, then reconnect the assistant's
|
|
258
|
+
netconverter server (assistants cache the tool list). `propose_operations` and `submit_conversion`
|
|
259
|
+
are write tools: the server lists them only where they are enabled for your tenant, and checks
|
|
260
|
+
and audits every call. `account` (`guided_migration`) and the remote `get_account` say which tools
|
|
261
|
+
this session has and why any are missing. A sign-in (`netconverter login --clerk`) or an
|
|
262
|
+
enterprise API key with `write:jobs` both work; pilot (Terminal Quick) keys have no prescan.
|
|
263
|
+
|
|
234
264
|
Remote NetConverter tools are proxied only from a fixed allowlist, and never a
|
|
235
|
-
`submit_*` tool
|
|
265
|
+
`submit_*` tool other than `submit_conversion` (a prescan id and a revision, no
|
|
266
|
+
configuration text). Default: `compare_against_intent`, `fetch`, `get_account`,
|
|
236
267
|
`get_acl_summary`, `get_critical_object_impact`, `get_dependency_chains`,
|
|
237
268
|
`get_evidence`, `get_interface_summary`, `get_job_brief`, `get_management_config`,
|
|
238
269
|
`get_nat_summary`, `get_object_dependencies`, `get_object_summary`, `get_report`,
|
|
239
270
|
`get_route_summary`, `get_target_config`, `get_translation_edge_summary`,
|
|
240
271
|
`get_unused_objects`, `get_vpn_summary`, `get_zone_summary`, `kb_explain`,
|
|
241
272
|
`kb_search`, `list_jobs`, `list_objects_with_attribute`, `list_rules_matching`,
|
|
242
|
-
`query_ir`, `search`, `select_job`, `simulate_flow`, `vendor_capability_lookup
|
|
273
|
+
`query_ir`, `search`, `select_job`, `simulate_flow`, `vendor_capability_lookup`,
|
|
274
|
+
`get_mapping_questions`, `validate_mapping`, `apply_mapping_answers`, `list_operations`,
|
|
275
|
+
`get_decision_document`, `validate_decision_document`, `propose_operations`, `submit_conversion`,
|
|
276
|
+
`set_view_level` (lowers the server's view for the session; it can never raise it).
|
|
243
277
|
At levels `none`, `masked` and `selected` (the default is masked; `full` uses the default list):
|
|
244
278
|
`list_jobs`, `select_job`, `get_account`, `search`, `fetch`,
|
|
245
279
|
`kb_search`, `kb_explain`, `vendor_capability_lookup`, `get_job_brief`,
|
|
246
|
-
`get_evidence`, `get_report`, plus the chosen sections' tools under `selected`. A listed tool appears
|
|
280
|
+
`get_evidence`, `get_report`, the three guided-mapping tools, plus the chosen sections' tools under `selected`. A listed tool appears
|
|
247
281
|
only if the server offers it.
|
|
248
282
|
The bridge sends the level on every request (`X-NetConverter-View: none|masked|selected|full`;
|
|
249
283
|
the server may only lower the grant's view, never raise it) and reads the view in force from
|
|
@@ -259,6 +293,7 @@ Environment: `NETCONVERTER_URL`, `NETCONVERTER_PROVIDER`, `NETCONVERTER_MODEL`,
|
|
|
259
293
|
your sign-in, while `mcp` prefers the sign-in and says on stderr which API key it leaves unused;
|
|
260
294
|
`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
295
|
the folder's exposure level, and an explicit flag wins),
|
|
296
|
+
`NETCONVERTER_MCP_UPLOAD_CONFIRM=0` (same as `mcp --no-upload-confirm`),
|
|
262
297
|
`NETCONVERTER_NO_UPDATE_CHECK=1` (no daily update check or notice; `account` then reports
|
|
263
298
|
`update_available: null`), `NETCONVERTER_KEYRING_TIMEOUT_S` (how long to wait for the OS keyring
|
|
264
299
|
before reporting it locked; default 5), `NETCONVERTER_CREDENTIAL_STORE`,
|
|
@@ -309,6 +344,8 @@ file is reported as a missing file, never as "not signed in".
|
|
|
309
344
|
| "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 |
|
|
310
345
|
| "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` |
|
|
311
346
|
| `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 |
|
|
347
|
+
| `submit_file` always fails `upload_declined` / `confirmation_required` (ChatGPT, Claude Code) | The assistant declines confirmation forms without showing them. Say yes in the conversation so it can retry with the `confirm_token`, or start the bridge with `--no-upload-confirm` (`NETCONVERTER_MCP_UPLOAD_CONFIRM=0`) |
|
|
348
|
+
| Guided tools (`list_operations`, `submit_conversion` …) missing | They need exposure level `full` (`netconverter privacy level full`, then reconnect the assistant); the two write tools also need the tenant to have them enabled. `account` → `guided_migration` says which |
|
|
312
349
|
| 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` |
|
|
313
350
|
| `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 |
|
|
314
351
|
|
|
@@ -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, Devin Desktop / 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, ChatGPT desktop agent, 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
|
|
@@ -14,7 +14,7 @@ Both need a NetConverter account with **MCP access enabled** by your administrat
|
|
|
14
14
|
|
|
15
15
|
- **[Getting access](getting-access.md)** — new users and administrators start here
|
|
16
16
|
- [claude.ai, Claude Desktop chat and the Claude mobile app](claude-ai.md) — remote connector
|
|
17
|
-
- [ChatGPT](chatgpt.md) — remote connector
|
|
17
|
+
- [ChatGPT](chatgpt.md) — desktop agent (terminal bridge: upload and guided migration) or remote connector
|
|
18
18
|
- [Claude Desktop](claude-desktop.md) — terminal bridge
|
|
19
19
|
- [Claude Code](claude-code.md) — terminal bridge
|
|
20
20
|
- [Cursor, Gemini CLI, Codex CLI, VS Code, Devin Desktop / Windsurf, LM Studio](other-assistants.md) — terminal bridge
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# ChatGPT
|
|
2
|
+
|
|
3
|
+
ChatGPT reaches NetConverter in two ways:
|
|
4
|
+
|
|
5
|
+
- **ChatGPT desktop app's agent (Codex)**, on your computer: it runs this terminal's bridge, so
|
|
6
|
+
it can **upload configuration files** by path and run a **guided migration** (prescan →
|
|
7
|
+
decisions → conversion). Setup below under *Upload files from ChatGPT*.
|
|
8
|
+
- **The hosted connector** (chatgpt.com, any ChatGPT app): reads your jobs, results, account
|
|
9
|
+
and the knowledge base; it cannot submit configurations. Setup under *Add the connector*.
|
|
10
|
+
|
|
11
|
+
`netconverter connect chatgpt` prints both.
|
|
12
|
+
|
|
13
|
+
## Upload files from ChatGPT (desktop app agent)
|
|
14
|
+
|
|
15
|
+
The ChatGPT desktop app's agent reads its MCP servers from `~/.codex/config.toml`, the same
|
|
16
|
+
file Codex CLI uses. Use a dedicated folder for your configurations (not your home folder):
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
netconverter login --clerk # once; or an enterprise API key with write:jobs
|
|
20
|
+
mkdir -p ~/migrations && cd ~/migrations
|
|
21
|
+
netconverter connect codex # adds [mcp_servers.netconverter] for this folder
|
|
22
|
+
netconverter privacy level full # needed for the guided-migration tools; type the phrase
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Then restart ChatGPT. If `~/.codex/config.toml` already has `[mcp_servers.netconverter]`,
|
|
26
|
+
`connect` shows the table instead of changing it: edit its `args` to
|
|
27
|
+
`["mcp", "--workspace", "/Users/<you>/migrations"]`.
|
|
28
|
+
|
|
29
|
+
What happens in a chat (*"Prescan ~/migrations/edge.cfg from ASA to Palo Alto XML and walk me
|
|
30
|
+
through the decisions"*):
|
|
31
|
+
|
|
32
|
+
1. ChatGPT asks to run `submit_file`: approve it in ChatGPT's own tool prompt.
|
|
33
|
+
2. ChatGPT cannot show the bridge's upload form (it declines it unseen), so the bridge sends
|
|
34
|
+
nothing and answers `confirmation_required`. ChatGPT asks you in the chat whether to upload
|
|
35
|
+
that file (path and size); only when you say yes does it repeat the call with the
|
|
36
|
+
single-use `confirm_token`. The file goes from disk to NetConverter; its text never passes
|
|
37
|
+
through ChatGPT. The job stops at a `psc_` prescan.
|
|
38
|
+
3. ChatGPT reads the decisions (`list_operations`, `get_decision_document`,
|
|
39
|
+
`validate_decision_document`), asks you about each one, records your choices with
|
|
40
|
+
`propose_operations`, and with your OK queues the conversion with `submit_conversion`
|
|
41
|
+
(asked in the chat the same way). `download` saves the Palo Alto output in the folder.
|
|
42
|
+
|
|
43
|
+
Exposure level: the guided-migration tools need `full` for the folder. At `masked` (the default)
|
|
44
|
+
the prescan still runs, and `account` says the tools are hidden and how to fix it. The write tools
|
|
45
|
+
(`propose_operations`, `submit_conversion`) are listed only where they are enabled for your
|
|
46
|
+
tenant. If you prefer ChatGPT's own tool approval as the only confirmation, add
|
|
47
|
+
`"--no-upload-confirm"` to the `args` (or set `NETCONVERTER_MCP_UPLOAD_CONFIRM=0`).
|
|
48
|
+
ChatGPT keeps the tool list from when it started: restart it after an update or a level change.
|
|
49
|
+
|
|
50
|
+
## Add the connector
|
|
51
|
+
|
|
52
|
+
1. In ChatGPT: **Settings → Apps & Connectors → Advanced settings** → turn on
|
|
53
|
+
**Developer mode**, then **Create** a custom connector.
|
|
54
|
+
2. Fill it in:
|
|
55
|
+
- **Name:** `NetConverter`
|
|
56
|
+
- **MCP server URL:** `https://api.netconverter.ai/mcp/v1`
|
|
57
|
+
- **Authentication:** OAuth. Under the advanced OAuth settings enter
|
|
58
|
+
**Client ID** `RjSv1z2Gms6iS96s` and leave the client secret empty.
|
|
59
|
+
3. Save, then sign in with your NetConverter account when asked.
|
|
60
|
+
4. In a chat, enable NetConverter from the **+** menu (Developer mode).
|
|
61
|
+
|
|
62
|
+
Developer mode and custom connectors depend on your ChatGPT plan and workspace
|
|
63
|
+
settings; on business workspaces an admin may need to allow them.
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "netconverter-cli"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.7.1"
|
|
8
8
|
description = "NetConverter CLI — any-vendor network configuration migration, validation and optimization, and a local MCP bridge for your AI assistant"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "LicenseRef-NetConverter-Proprietary"
|
|
@@ -225,7 +225,7 @@ class ExternalClient(Client):
|
|
|
225
225
|
"""
|
|
226
226
|
|
|
227
227
|
_ALLOWED = re.compile(
|
|
228
|
-
r"(?:me|capabilities|jobs|jobs/[A-Za-z0-9_-]{1,80}(?:/translated|/report|/evidence\.xlsx|/findings\.sarif)?)\Z"
|
|
228
|
+
r"(?:me|capabilities|jobs|jobs/[A-Za-z0-9_-]{1,80}(?:/translated|/report|/evidence\.xlsx|/findings\.sarif|/diagrams/render)?)\Z"
|
|
229
229
|
)
|
|
230
230
|
|
|
231
231
|
def me(self):
|
|
@@ -279,3 +279,21 @@ class ExternalClient(Client):
|
|
|
279
279
|
if response.is_error:
|
|
280
280
|
raise self._error(response, request_id)
|
|
281
281
|
return response.content
|
|
282
|
+
|
|
283
|
+
def diagram(self, job_id: str, recipe: dict, *, max_bytes=32 * 1024 * 1024) -> bytes:
|
|
284
|
+
"""Fixed authenticated endpoint; the expected hash binds revision and view."""
|
|
285
|
+
path = f"jobs/{self.identifier(job_id)}/diagrams/render"
|
|
286
|
+
request_id = "req_" + uuid.uuid4().hex
|
|
287
|
+
try:
|
|
288
|
+
with self.http.stream("POST", path, json=recipe,
|
|
289
|
+
headers={"X-Request-ID": request_id}) as response:
|
|
290
|
+
content = bytearray()
|
|
291
|
+
for chunk in response.iter_bytes(chunk_size=64 * 1024):
|
|
292
|
+
if len(content) + len(chunk) > max_bytes:
|
|
293
|
+
raise APIError(413, "diagram_too_large", request_id)
|
|
294
|
+
content.extend(chunk)
|
|
295
|
+
if response.status_code != 200:
|
|
296
|
+
raise self._error(httpx.Response(response.status_code, content=bytes(content)), request_id)
|
|
297
|
+
return bytes(content)
|
|
298
|
+
except httpx.HTTPError:
|
|
299
|
+
raise APIError(0, "connection_failed", request_id) from None
|
|
@@ -11,7 +11,7 @@ from __future__ import annotations
|
|
|
11
11
|
|
|
12
12
|
from dataclasses import dataclass, field
|
|
13
13
|
|
|
14
|
-
JOB_TYPES = ("convert", "validate", "optimize")
|
|
14
|
+
JOB_TYPES = ("convert", "validate", "optimize", "prescan")
|
|
15
15
|
QUICK_SOURCES = ("cisco_asa", "palo_alto_set", "palo_alto_xml", "palo_alto_panorama")
|
|
16
16
|
QUICK_LIMIT_BYTES = 50_000
|
|
17
17
|
DEVICE_TYPES = ("firewall", "router", "switch")
|
|
@@ -32,6 +32,7 @@ LABELS = {
|
|
|
32
32
|
"convert": "Convert",
|
|
33
33
|
"validate": "Validate",
|
|
34
34
|
"optimize": "Optimize",
|
|
35
|
+
"prescan": "Prescan",
|
|
35
36
|
"analyze": "Validate",
|
|
36
37
|
}
|
|
37
38
|
FIELD_LABELS = {
|
|
@@ -191,6 +191,11 @@ def mcp_view_default() -> str | None:
|
|
|
191
191
|
return value if value in MCP_VIEWS else None
|
|
192
192
|
|
|
193
193
|
|
|
194
|
+
def mcp_upload_confirm_default() -> bool:
|
|
195
|
+
"""`mcp` asks for upload/convert confirmation forms unless NETCONVERTER_MCP_UPLOAD_CONFIRM is 0/false/off (#37)."""
|
|
196
|
+
return os.getenv("NETCONVERTER_MCP_UPLOAD_CONFIRM", "").strip().lower() not in {"0", "false", "no", "off"}
|
|
197
|
+
|
|
198
|
+
|
|
194
199
|
def mcp_auth_default() -> str:
|
|
195
200
|
"""`mcp --auth` default: NETCONVERTER_MCP_AUTH, else NETCONVERTER_AUTH (#16), else auto."""
|
|
196
201
|
for name in ("NETCONVERTER_MCP_AUTH", "NETCONVERTER_AUTH"):
|
|
@@ -281,7 +286,7 @@ def run_mcp(args):
|
|
|
281
286
|
options["credential_loader"] = lambda: choose_mcp_credential(args.auth, args.server, mcp_url)
|
|
282
287
|
run_stdio(Bridge(args.workspace, args.server, rest, remote, strict=strict,
|
|
283
288
|
credential_source=source, level=cap.level, sections=cap.sections,
|
|
284
|
-
workspace_level=True, **options))
|
|
289
|
+
workspace_level=True, upload_confirm=getattr(args, "upload_confirm", True), **options))
|
|
285
290
|
finally:
|
|
286
291
|
if remote:
|
|
287
292
|
remote.close()
|
|
@@ -606,7 +611,13 @@ def parser():
|
|
|
606
611
|
mcp.add_argument("--strict", dest="view", action="store_const", const="strict",
|
|
607
612
|
help="at most masked (the strict view)")
|
|
608
613
|
mcp.add_argument("--full", dest="view", action="store_const", const="full",
|
|
609
|
-
help="up to full, when this folder's level is full"
|
|
614
|
+
help="up to full, when this folder's level is full (`netconverter privacy level full`; "
|
|
615
|
+
"the guided-migration tools, prescan to submit_conversion, need it)")
|
|
616
|
+
mcp.add_argument("--no-upload-confirm", dest="upload_confirm", action="store_false",
|
|
617
|
+
default=mcp_upload_confirm_default(),
|
|
618
|
+
help="never send a confirmation form before an upload or a queued conversion; the AI "
|
|
619
|
+
"client's own tool approval confirms instead (for clients that decline forms "
|
|
620
|
+
"unseen, e.g. ChatGPT, Claude Code; NETCONVERTER_MCP_UPLOAD_CONFIRM=0)")
|
|
610
621
|
mcp.add_argument("--workspace", default=argparse.SUPPRESS, help="folder the file tools may read and write")
|
|
611
622
|
from .connect import CLIENTS as _AI_CLIENTS
|
|
612
623
|
connect = subs.add_parser(
|
|
@@ -371,7 +371,12 @@ REMOTE_STEPS = {
|
|
|
371
371
|
" Authentication: OAuth. Under advanced OAuth settings enter the NetConverter OAuth\n"
|
|
372
372
|
" client ID your administrator gives you, then sign in with your\n"
|
|
373
373
|
" NetConverter account when asked.\n"
|
|
374
|
-
"Then enable NetConverter in a chat from the + menu (Developer mode)
|
|
374
|
+
"Then enable NetConverter in a chat from the + menu (Developer mode).\n"
|
|
375
|
+
"To upload configuration files from ChatGPT: the ChatGPT desktop app's agent (Codex) runs\n"
|
|
376
|
+
"this bridge from ~/.codex/config.toml. In your migrations folder run\n"
|
|
377
|
+
"`netconverter connect codex` and, for the guided-migration tools,\n"
|
|
378
|
+
"`netconverter privacy level full`; then restart ChatGPT. ChatGPT cannot show the\n"
|
|
379
|
+
"upload form, so it asks you in the chat before each upload (docs/connect/chatgpt.md)."),
|
|
375
380
|
"claude-ai": (
|
|
376
381
|
"claude.ai (web and mobile)",
|
|
377
382
|
"On claude.ai: Settings → Connectors → Add custom connector.\n"
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"""Download a governed diagram recipe; never follow a model-supplied URL."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import hashlib
|
|
5
|
+
import struct
|
|
6
|
+
from typing import Literal
|
|
7
|
+
from pydantic import BaseModel, ConfigDict, Field
|
|
8
|
+
|
|
9
|
+
from .workspace import WorkspaceError
|
|
10
|
+
|
|
11
|
+
MAX_PREVIEW_BYTES = 2 * 1024 * 1024
|
|
12
|
+
MAX_PREVIEW_EDGE = 4096
|
|
13
|
+
MAX_PREVIEW_PIXELS = 8_000_000
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class DiagramArtifact(BaseModel):
|
|
17
|
+
model_config = ConfigDict(extra='forbid', strict=True)
|
|
18
|
+
kind: Literal['topology', 'comparison', 'traffic', 'nat', 'policy'] = 'topology'
|
|
19
|
+
side: Literal['source', 'target'] = 'source'
|
|
20
|
+
max_nodes: int = Field(default=60, ge=4, le=120)
|
|
21
|
+
format: Literal['svg', 'png', 'pdf', 'drawio', 'json']
|
|
22
|
+
view: Literal['default', 'strict'] = 'default'
|
|
23
|
+
expected_sha256: str = Field(pattern=r'^[a-f0-9]{64}$')
|
|
24
|
+
flow: dict | None = None
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class DiagramPreviewArtifact(DiagramArtifact):
|
|
28
|
+
format: Literal['png']
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def fetch_diagram(client, job_id, recipe, *, strict=False, preview=False):
|
|
32
|
+
"""One recipe/view/hash contract for disk downloads and explicit previews."""
|
|
33
|
+
artifact = DiagramArtifact.model_validate(recipe)
|
|
34
|
+
if preview and artifact.format != 'png':
|
|
35
|
+
raise ValueError('Previews require a PNG recipe from get_diagram')
|
|
36
|
+
if artifact.flow is not None and artifact.kind != 'traffic':
|
|
37
|
+
raise ValueError('Flow inputs require a traffic diagram')
|
|
38
|
+
if strict:
|
|
39
|
+
artifact.view = 'strict'
|
|
40
|
+
if artifact.flow is not None:
|
|
41
|
+
raise ValueError('Explicit flow inputs are unavailable in strict view')
|
|
42
|
+
options = {'max_bytes': MAX_PREVIEW_BYTES} if preview else {}
|
|
43
|
+
content = client.diagram(job_id, artifact.model_dump(exclude_none=True), **options)
|
|
44
|
+
if hashlib.sha256(content).hexdigest() != artifact.expected_sha256:
|
|
45
|
+
raise WorkspaceError('Artifact checksum failed; no diagram was returned')
|
|
46
|
+
return artifact, content
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def preview_dimensions(content):
|
|
50
|
+
"""Reject non-PNG and oversized canvases before sending an image to the IDE."""
|
|
51
|
+
if len(content) > MAX_PREVIEW_BYTES:
|
|
52
|
+
raise WorkspaceError('Diagram preview exceeds the 2 MiB limit; download it instead')
|
|
53
|
+
if (len(content) < 33 or content[:8] != b'\x89PNG\r\n\x1a\n'
|
|
54
|
+
or content[8:16] != b'\x00\x00\x00\x0dIHDR'):
|
|
55
|
+
raise WorkspaceError('Diagram preview is not a PNG image')
|
|
56
|
+
width, height = struct.unpack('>II', content[16:24])
|
|
57
|
+
if (not width or not height or max(width, height) > MAX_PREVIEW_EDGE
|
|
58
|
+
or width * height > MAX_PREVIEW_PIXELS):
|
|
59
|
+
raise WorkspaceError('Diagram preview canvas is too large; request fewer nodes or download it')
|
|
60
|
+
return width, height
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def download_diagram(client, output, job_id, recipe, *, strict=False):
|
|
64
|
+
artifact, content = fetch_diagram(client, job_id, recipe, strict=strict)
|
|
65
|
+
# Include immutable byte identity, preserving previous document revisions.
|
|
66
|
+
filename = f'{artifact.kind}-{artifact.side}-{artifact.expected_sha256[:16]}.{artifact.format}'
|
|
67
|
+
return output.save_artifact(job_id, filename, content, artifact.expected_sha256)
|
|
@@ -57,7 +57,7 @@ BODY_OPTIONS = {
|
|
|
57
57
|
"properties": {k: {"type": "boolean"} for k in OPTIMIZATION_FLAGS},
|
|
58
58
|
"description": "Optimize only: analysis switches."}, ("optimize",)),
|
|
59
59
|
"file_name": ({**_text(255), "description": "Name shown for the job in the portal."},
|
|
60
|
-
("convert", "validate", "optimize")),
|
|
60
|
+
("convert", "validate", "optimize", "prescan")),
|
|
61
61
|
}
|
|
62
62
|
DECISION_OPTIONS = {
|
|
63
63
|
"zone_mapping": ({"type": "object", "additionalProperties": _text(200), "maxProperties": 500,
|