cyver-mcp 0.4.0__tar.gz

cyver_mcp-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thoropass
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cyver_mcp-0.4.0/MANIFEST.in

@@ -0,0 +1 @@
+exclude README.md

cyver_mcp-0.4.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: cyver-mcp
+Version: 0.4.0
+Summary: MCP server exposing the Cyver reporting platform to Claude via the cyver-reporting wrapper.
+Author-email: Husain Murabbi <husain.murabbi@thoropass.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cyver-reporting>=0.0.6
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: license-file
+
+# cyver-mcp
+
+A Model Context Protocol (MCP) server that lets Claude read from and
+write to the [Cyver](https://cyver.io/) pentest reporting platform
+through chat. Wraps the
+[`cyver-reporting`](https://pypi.org/project/cyver-reporting/) Python
+client and exposes 32 tools across reads, writes, and a single gated
+destructive write.
+
+## Features
+
+- **20 read tools** (always on): projects, continuous projects,
+  findings, clients, users, teams, client assets, plus reference
+  data (vulnerability types, report templates, compliance norm
+  templates), finding-library lookups, and a binary-file download
+  tool that returns inline image content for screenshots / PoC
+  captures.
+- **11 write tools** (opt-in via `CYVER_ALLOW_WRITES=1`): create
+  findings (from scratch or from a library template, with inline
+  evidence), append evidence to existing findings, change finding
+  status non-destructively, create / move projects, create clients
+  and assets, attach users / assets / teams to projects, upload
+  binary evidence files.
+- **1 destructive write** (additionally `CYVER_ALLOW_DESTRUCTIVE=1`):
+  `update_finding`, a full PUT that overwrites every field not
+  re-supplied. For status-only changes use the non-destructive
+  `update_finding_status` instead.
+- **Dry-run preview** on every write tool. Returns the would-be
+  request body without sending.
+- **Audit log** as JSON lines on every write. Default sink is
+  stderr; set `CYVER_AUDIT_LOG` to a file path to also append there.
+  Sensitive values redacted automatically.
+- **Severity 0..4 ↔ label** and **finding status 1..14 ↔ label**
+  mappings applied automatically on reads and accepted by name on
+  writes.
+- **No secrets in the MCP config block.** The server loads `.env`
+  itself.
+
+## Requirements
+
+- Python 3.10 or newer
+- A Cyver portal account (username + password; 2FA supported)
+- Claude Desktop or Claude Code
+
+Pure Python, runs on macOS, Linux, and Windows.
+
+## Installation
+
+```bash
+pipx install cyver-mcp
+```
+
+`pipx` is the recommended path for CLI tools. Plain
+`pip install cyver-mcp` works too if you prefer to manage your own
+venv.
+
+## Quick Start
+
+### One-time setup
+
+Run the wizard. It writes `~/.config/cyver-mcp/.env` (chmod 600) and
+primes the encrypted refresh-token cache.
+
+```bash
+cyver-mcp setup
+```
+
+Prompts:
+
+```
+Portal hostname (e.g. app.cyver.io): app.cyver.io
+Username or email: you@example.com
+Password: ********
+Enable write tools (create findings, projects, etc.)? [y/N]: y
+2FA required. A code has been sent to your email.
+Enter 2FA code: 123456
+OK. Token cached for pentester session on app.cyver.io.
+```
+
+### Re-authenticate later
+
+When the cached token expires, refresh without re-running setup:
+
+```bash
+cyver-mcp login
+```
+
+Prompts for a 2FA code only when the wrapper raises
+`Cyver2FARequired`. Otherwise silent.
+
+To wipe the cache:
+
+```bash
+cyver-mcp logout
+```
+
+### Connect Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "cyver": {
+      "command": "cyver-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The cyver tools appear in the tool list.
+
+### Connect Claude Code
+
+Add the same block to `.mcp.json` in any project where you want the
+tools available, then restart Claude Code in that directory.
+
+### Try it
+
+In a new chat:
+
+> List three projects from Cyver.
+
+Claude calls `search_projects` and returns three real project
+records. To verify writes (if enabled):
+
+> Use create_finding with dry_run=true to preview a Critical finding
+> for project P-YYYY-NNNN about MFA missing.
+
+You see a `would_send` payload back, with no actual change made on
+the portal.
+
+## Tools
+
+### Reads (20, always registered)
+
+| Tool                              | Purpose                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------ |
+| `search_projects`                 | Filter projects by client, status, or name.                              |
+| `get_project`                     | Full detail for one project.                                             |
+| `list_project_report_versions`    | Versions of the project's report.                                        |
+| `list_project_checklists`         | Checklists associated with a project.                                    |
+| `list_project_compliance_norms`   | Compliance norms attached to a project.                                  |
+| `search_continuous_projects`      | Filter continuous projects.                                              |
+| `get_continuous_project`          | Full detail for one continuous project.                                  |
+| `search_findings`                 | Filter by project, status, severity, type, client, or free-text. Includes `severityLabel` and `statusLabel`. |
+| `get_finding`                     | Full finding detail (evidence included by default).                      |
+| `search_clients`                  | Filter clients by name/status.                                           |
+| `get_client`                      | Full client detail.                                                      |
+| `list_client_assets`              | Assets owned by a client.                                                |
+| `search_users`                    | Filter users by name, client, or role.                                   |
+| `search_teams`                    | Filter teams by name, client, or project.                                |
+| `list_vulnerability_types`        | Vulnerability type catalog.                                              |
+| `list_compliance_norm_templates`  | Available compliance norm templates.                                     |
+| `list_report_templates`           | Available report templates.                                              |
+| `list_finding_libraries`          | Finding-library catalog.                                                 |
+| `list_finding_templates`          | Templates inside a library.                                              |
+| `download_project_file`           | Fetch a project file's bytes; returns an inline image content block for `image/*` MIMEs. |
+
+### Writes (11, opt-in via `CYVER_ALLOW_WRITES=1`)
+
+With the flag unset, the tools are not registered at all (Claude
+can't see or call them).
+
+| Tool                          | Purpose                                                          |
+| ----------------------------- | ---------------------------------------------------------------- |
+| `create_finding`              | Create a finding on a project (with optional inline evidence; supports `template_id` for from-template creation). |
+| `update_finding_status`       | Change a finding's status without touching anything else (load-modify-save). |
+| `add_evidence_to_finding`     | Append evidence records to an existing finding (true add).       |
+| `create_project`              | Create a project for a client.                                   |
+| `update_project_status`       | Move a project (ONBOARDING / TESTING / REPORTING / REMEDIATION / COMPLETED). |
+| `create_client`               | Create a new client.                                             |
+| `create_client_asset`         | Create an asset under a client.                                  |
+| `add_users_to_project`        | Append users (true add, no replace).                             |
+| `add_assets_to_project`       | Append assets (true add, no replace).                            |
+| `add_teams_to_project`        | Append teams (true add, no replace).                             |
+| `upload_evidence_to_project`  | Upload a binary file (screenshot, PoC, etc.) as project evidence.|
+
+Every write tool accepts `dry_run=True` and emits one audit-log
+line per call.
+
+### Destructive writes (1, additionally `CYVER_ALLOW_DESTRUCTIVE=1`)
+
+| Tool              | Purpose                                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------- |
+| `update_finding`  | Full PUT update of an existing finding. Overwrites every field not re-supplied, replaces evidence list when supplied. |
+
+For status-only changes prefer `update_finding_status` (non-
+destructive, only needs `CYVER_ALLOW_WRITES`).
+
+## Configuration
+
+### Environment variables
+
+The server reads `.env` from `$CYVER_CONFIG`, then `./.env`, then
+`~/.config/cyver-mcp/.env`. Process env always wins over file values.
+
+| Variable                  | Required  | Purpose                                                                       |
+| ------------------------- | --------- | ----------------------------------------------------------------------------- |
+| `CYVER_PORTAL`            | yes       | Portal hostname, e.g. `app.cyver.io`.                                         |
+| `CYVER_USERNAME`          | preferred | Cyver username or email. Primary auth path.                                   |
+| `CYVER_PASSWORD`          | preferred | Used with `CYVER_USERNAME`.                                                   |
+| `CYVER_API_KEY`           | optional  | Static API key. Leave blank to use username/password.                         |
+| `CYVER_SESSION_TYPE`      | optional  | `pentester` (default) or `client`.                                            |
+| `CYVER_ALLOW_WRITES`      | optional  | `1` to register the 11 write tools. Default: off.                             |
+| `CYVER_ALLOW_DESTRUCTIVE` | optional  | `1` to also register `update_finding`. Has no effect without `CYVER_ALLOW_WRITES=1`. |
+| `CYVER_AUDIT_LOG`         | optional  | Path to append audit-log JSON lines. Default: stderr.                         |
+| `CYVER_CONFIG`            | optional  | Override the `.env` search path.                                              |
+
+Username/password is the preferred path. Static API keys are
+supported as a fallback when one is available.
+
+### Audit log
+
+Every write tool (live or dry-run) emits one JSON object per line:
+
+```json
+{"ts":"2026-04-27T10:46:21Z","tool":"create_finding","target":"<project_id>","result":"ok","params":{...}}
+```
+
+`result` is one of `ok`, `dry_run`, or `error:<ExceptionName>`.
+Sensitive values (passwords, tokens, 2FA codes) are redacted before
+the line is written.
+
+## License
+
+MIT.
+
+Developed and maintained by penetration testers at
+[Thoropass](https://thoropass.com/).

cyver_mcp-0.4.0/README.pypi.md

@@ -0,0 +1,231 @@
+# cyver-mcp
+
+A Model Context Protocol (MCP) server that lets Claude read from and
+write to the [Cyver](https://cyver.io/) pentest reporting platform
+through chat. Wraps the
+[`cyver-reporting`](https://pypi.org/project/cyver-reporting/) Python
+client and exposes 32 tools across reads, writes, and a single gated
+destructive write.
+
+## Features
+
+- **20 read tools** (always on): projects, continuous projects,
+  findings, clients, users, teams, client assets, plus reference
+  data (vulnerability types, report templates, compliance norm
+  templates), finding-library lookups, and a binary-file download
+  tool that returns inline image content for screenshots / PoC
+  captures.
+- **11 write tools** (opt-in via `CYVER_ALLOW_WRITES=1`): create
+  findings (from scratch or from a library template, with inline
+  evidence), append evidence to existing findings, change finding
+  status non-destructively, create / move projects, create clients
+  and assets, attach users / assets / teams to projects, upload
+  binary evidence files.
+- **1 destructive write** (additionally `CYVER_ALLOW_DESTRUCTIVE=1`):
+  `update_finding`, a full PUT that overwrites every field not
+  re-supplied. For status-only changes use the non-destructive
+  `update_finding_status` instead.
+- **Dry-run preview** on every write tool. Returns the would-be
+  request body without sending.
+- **Audit log** as JSON lines on every write. Default sink is
+  stderr; set `CYVER_AUDIT_LOG` to a file path to also append there.
+  Sensitive values redacted automatically.
+- **Severity 0..4 ↔ label** and **finding status 1..14 ↔ label**
+  mappings applied automatically on reads and accepted by name on
+  writes.
+- **No secrets in the MCP config block.** The server loads `.env`
+  itself.
+
+## Requirements
+
+- Python 3.10 or newer
+- A Cyver portal account (username + password; 2FA supported)
+- Claude Desktop or Claude Code
+
+Pure Python, runs on macOS, Linux, and Windows.
+
+## Installation
+
+```bash
+pipx install cyver-mcp
+```
+
+`pipx` is the recommended path for CLI tools. Plain
+`pip install cyver-mcp` works too if you prefer to manage your own
+venv.
+
+## Quick Start
+
+### One-time setup
+
+Run the wizard. It writes `~/.config/cyver-mcp/.env` (chmod 600) and
+primes the encrypted refresh-token cache.
+
+```bash
+cyver-mcp setup
+```
+
+Prompts:
+
+```
+Portal hostname (e.g. app.cyver.io): app.cyver.io
+Username or email: you@example.com
+Password: ********
+Enable write tools (create findings, projects, etc.)? [y/N]: y
+2FA required. A code has been sent to your email.
+Enter 2FA code: 123456
+OK. Token cached for pentester session on app.cyver.io.
+```
+
+### Re-authenticate later
+
+When the cached token expires, refresh without re-running setup:
+
+```bash
+cyver-mcp login
+```
+
+Prompts for a 2FA code only when the wrapper raises
+`Cyver2FARequired`. Otherwise silent.
+
+To wipe the cache:
+
+```bash
+cyver-mcp logout
+```
+
+### Connect Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "cyver": {
+      "command": "cyver-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The cyver tools appear in the tool list.
+
+### Connect Claude Code
+
+Add the same block to `.mcp.json` in any project where you want the
+tools available, then restart Claude Code in that directory.
+
+### Try it
+
+In a new chat:
+
+> List three projects from Cyver.
+
+Claude calls `search_projects` and returns three real project
+records. To verify writes (if enabled):
+
+> Use create_finding with dry_run=true to preview a Critical finding
+> for project P-YYYY-NNNN about MFA missing.
+
+You see a `would_send` payload back, with no actual change made on
+the portal.
+
+## Tools
+
+### Reads (20, always registered)
+
+| Tool                              | Purpose                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------ |
+| `search_projects`                 | Filter projects by client, status, or name.                              |
+| `get_project`                     | Full detail for one project.                                             |
+| `list_project_report_versions`    | Versions of the project's report.                                        |
+| `list_project_checklists`         | Checklists associated with a project.                                    |
+| `list_project_compliance_norms`   | Compliance norms attached to a project.                                  |
+| `search_continuous_projects`      | Filter continuous projects.                                              |
+| `get_continuous_project`          | Full detail for one continuous project.                                  |
+| `search_findings`                 | Filter by project, status, severity, type, client, or free-text. Includes `severityLabel` and `statusLabel`. |
+| `get_finding`                     | Full finding detail (evidence included by default).                      |
+| `search_clients`                  | Filter clients by name/status.                                           |
+| `get_client`                      | Full client detail.                                                      |
+| `list_client_assets`              | Assets owned by a client.                                                |
+| `search_users`                    | Filter users by name, client, or role.                                   |
+| `search_teams`                    | Filter teams by name, client, or project.                                |
+| `list_vulnerability_types`        | Vulnerability type catalog.                                              |
+| `list_compliance_norm_templates`  | Available compliance norm templates.                                     |
+| `list_report_templates`           | Available report templates.                                              |
+| `list_finding_libraries`          | Finding-library catalog.                                                 |
+| `list_finding_templates`          | Templates inside a library.                                              |
+| `download_project_file`           | Fetch a project file's bytes; returns an inline image content block for `image/*` MIMEs. |
+
+### Writes (11, opt-in via `CYVER_ALLOW_WRITES=1`)
+
+With the flag unset, the tools are not registered at all (Claude
+can't see or call them).
+
+| Tool                          | Purpose                                                          |
+| ----------------------------- | ---------------------------------------------------------------- |
+| `create_finding`              | Create a finding on a project (with optional inline evidence; supports `template_id` for from-template creation). |
+| `update_finding_status`       | Change a finding's status without touching anything else (load-modify-save). |
+| `add_evidence_to_finding`     | Append evidence records to an existing finding (true add).       |
+| `create_project`              | Create a project for a client.                                   |
+| `update_project_status`       | Move a project (ONBOARDING / TESTING / REPORTING / REMEDIATION / COMPLETED). |
+| `create_client`               | Create a new client.                                             |
+| `create_client_asset`         | Create an asset under a client.                                  |
+| `add_users_to_project`        | Append users (true add, no replace).                             |
+| `add_assets_to_project`       | Append assets (true add, no replace).                            |
+| `add_teams_to_project`        | Append teams (true add, no replace).                             |
+| `upload_evidence_to_project`  | Upload a binary file (screenshot, PoC, etc.) as project evidence.|
+
+Every write tool accepts `dry_run=True` and emits one audit-log
+line per call.
+
+### Destructive writes (1, additionally `CYVER_ALLOW_DESTRUCTIVE=1`)
+
+| Tool              | Purpose                                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------- |
+| `update_finding`  | Full PUT update of an existing finding. Overwrites every field not re-supplied, replaces evidence list when supplied. |
+
+For status-only changes prefer `update_finding_status` (non-
+destructive, only needs `CYVER_ALLOW_WRITES`).
+
+## Configuration
+
+### Environment variables
+
+The server reads `.env` from `$CYVER_CONFIG`, then `./.env`, then
+`~/.config/cyver-mcp/.env`. Process env always wins over file values.
+
+| Variable                  | Required  | Purpose                                                                       |
+| ------------------------- | --------- | ----------------------------------------------------------------------------- |
+| `CYVER_PORTAL`            | yes       | Portal hostname, e.g. `app.cyver.io`.                                         |
+| `CYVER_USERNAME`          | preferred | Cyver username or email. Primary auth path.                                   |
+| `CYVER_PASSWORD`          | preferred | Used with `CYVER_USERNAME`.                                                   |
+| `CYVER_API_KEY`           | optional  | Static API key. Leave blank to use username/password.                         |
+| `CYVER_SESSION_TYPE`      | optional  | `pentester` (default) or `client`.                                            |
+| `CYVER_ALLOW_WRITES`      | optional  | `1` to register the 11 write tools. Default: off.                             |
+| `CYVER_ALLOW_DESTRUCTIVE` | optional  | `1` to also register `update_finding`. Has no effect without `CYVER_ALLOW_WRITES=1`. |
+| `CYVER_AUDIT_LOG`         | optional  | Path to append audit-log JSON lines. Default: stderr.                         |
+| `CYVER_CONFIG`            | optional  | Override the `.env` search path.                                              |
+
+Username/password is the preferred path. Static API keys are
+supported as a fallback when one is available.
+
+### Audit log
+
+Every write tool (live or dry-run) emits one JSON object per line:
+
+```json
+{"ts":"2026-04-27T10:46:21Z","tool":"create_finding","target":"<project_id>","result":"ok","params":{...}}
+```
+
+`result` is one of `ok`, `dry_run`, or `error:<ExceptionName>`.
+Sensitive values (passwords, tokens, 2FA codes) are redacted before
+the line is written.
+
+## License
+
+MIT.
+
+Developed and maintained by penetration testers at
+[Thoropass](https://thoropass.com/).

cyver_mcp-0.4.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cyver-mcp"
+version = "0.4.0"
+description = "MCP server exposing the Cyver reporting platform to Claude via the cyver-reporting wrapper."
+readme = "README.pypi.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Husain Murabbi", email = "husain.murabbi@thoropass.com" }]
+dependencies = [
+    # v0.0.4 ships heylaika/cyver-reporting PR #21 (labelList fix).
+    # PR #23 (DONE status) is still open upstream; harmless for us because
+    # our raw _send_api_request path doesn't go through the wrapper's
+    # project-status validator. Bump the floor when #23 ships.
+    "cyver-reporting>=0.0.6",
+    "mcp[cli]>=1.2.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.scripts]
+cyver-mcp = "cyver_mcp.__main__:main"
+cyver-mcp-login = "cyver_mcp.login:main"
+cyver-mcp-logout = "cyver_mcp.logout:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

cyver_mcp-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cyver_mcp-0.4.0/src/cyver_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for the Cyver reporting platform."""
+
+__version__ = "0.4.0"

cyver_mcp-0.4.0/src/cyver_mcp/__main__.py

@@ -0,0 +1,73 @@
+"""Entry point for `cyver-mcp` (and `python -m cyver_mcp`).
+
+Subcommand dispatcher modeled on `aws` / `gh`:
+
+- `cyver-mcp setup`   — one-time interactive setup wizard
+- `cyver-mcp login`   — re-authenticate (refresh token cache)
+- `cyver-mcp logout`  — wipe token cache
+- `cyver-mcp`         — run the MCP server (default)
+
+The default-to-server behavior preserves the existing Claude Desktop
+config (`["-m", "cyver_mcp"]`) — no edits needed when upgrading from
+v0.3.x.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="cyver-mcp",
+        description=(
+            "MCP server for the Cyver pentest reporting platform. "
+            "Run with no subcommand to start the server."
+        ),
+    )
+    subparsers = parser.add_subparsers(dest="cmd")
+
+    setup_p = subparsers.add_parser(
+        "setup",
+        help="One-time setup wizard (writes .env and primes token cache)",
+    )
+    setup_p.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing config file",
+    )
+
+    subparsers.add_parser(
+        "login",
+        help="Re-authenticate using saved config (refresh token cache)",
+    )
+    subparsers.add_parser(
+        "logout",
+        help="Wipe the encrypted token cache",
+    )
+
+    args = parser.parse_args()
+
+    if args.cmd == "setup":
+        from cyver_mcp import setup_wizard
+
+        return setup_wizard.main(force=args.force)
+    if args.cmd == "login":
+        from cyver_mcp import login
+
+        return login.main()
+    if args.cmd == "logout":
+        from cyver_mcp import logout
+
+        return logout.main()
+
+    # No subcommand → run the MCP server.
+    from cyver_mcp.server import main as server_main
+
+    server_main()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())