cystene 0.1.0__tar.gz

cystene-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: cystene
+Version: 0.1.0
+Summary: Cystene CLI + MCP — scan your infrastructure from your terminal or your AI assistant
+Keywords: cystene,security,scanner,pentest,espm,mcp,cli,ai,claude,llm
+Author: Robert Radoslav
+Author-email: Robert Radoslav <43938206+rbtrsv@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: Security
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: click>=8.4.2
+Requires-Dist: fastmcp>=3.4.4
+Requires-Dist: httpx>=0.28.1
+Requires-Python: >=3.12
+Project-URL: Documentation, https://www.cystene.com
+Project-URL: Homepage, https://www.cystene.com
+Project-URL: PyPI, https://pypi.org/project/cystene/
+Description-Content-Type: text/markdown
+
+# cystene
+
+**Cystene CLI + MCP** — scan your infrastructure from your terminal or your AI assistant.
+
+One `pip install` ships three entry points over a single shared core:
+
+- **`cystene`** — the CLI. `cystene scan <url>` runs the engines and prints ranked findings.
+- **`cystene-mcp`** — the MCP server over stdio (Claude Desktop / Claude Code / Cursor).
+- **`cystene-mcp-http`** — the MCP server over HTTP + OAuth (remote, `mcp.cystene.com`).
+
+## Install
+
+```bash
+pip install cystene
+# or:  uv tool install cystene
+cystene --help
+```
+
+## Login
+
+```bash
+cystene login            # browser (OAuth device flow)
+cystene login --basic    # email/password in the terminal (headless / CI)
+cystene status           # show current auth status
+```
+
+Credentials are stored locally in `~/.cystene/credentials.json` (chmod 600). Your
+password never reaches the AI — login happens in your browser or terminal.
+
+## Scan from the terminal
+
+```bash
+cystene scan https://app.example.com
+cystene scan https://app.example.com --engines web_scan,baas_scan,secret_scan
+cystene scan https://app.example.com --fail-on critical
+```
+
+`scan` finds or creates a target for the URL, runs the external engines, prints the
+findings ranked worst-first with severity + confidence, and exits non-zero when any
+finding is at or above `--fail-on` (default `high`) — drop it straight into CI:
+
+```yaml
+- run: pip install cystene && cystene login --basic <<< "$CYSTENE_EMAIL\n$CYSTENE_PASSWORD"
+- run: cystene scan "$DEPLOY_URL" --fail-on high
+```
+
+## Use from your AI assistant (MCP)
+
+After `cystene login`, wire the stdio server into your client:
+
+**Claude Code:**
+
+```bash
+claude mcp add cystene -- cystene-mcp
+```
+
+**Claude Desktop / Cursor** — add to the MCP config:
+
+```json
+{
+  "mcpServers": {
+    "cystene": { "command": "cystene-mcp" }
+  }
+}
+```
+
+Then ask: *"Scan https://app.example.com and show me the critical findings."*
+
+## Tools (MCP)
+
+| Group | Tools |
+|-------|-------|
+| **Context** | get_permissions, list_organizations, set_organization |
+| **Infrastructure** | list_scan_targets, create_scan_target |
+| **Execution** | scan, list_scan_templates, create_scan_template, start_scan, get_scan_job, list_scan_jobs |
+| **Discovery** | list_findings, get_finding, list_assets, get_dashboard, generate_report |
+
+## Security
+
+- Passwords never reach the AI — login happens in your browser or terminal.
+- Credentials stored locally in `~/.cystene/credentials.json` (chmod 600).
+- Automatic token refresh on expiry.
+- No destructive operations exposed over MCP.
+- All API validations, permissions, subscription gating, and audit logging apply.
+
+## Requirements
+
+- Python 3.12+
+- A [Cystene](https://www.cystene.com) account

cystene-0.1.0/README.md

@@ -0,0 +1,89 @@
+# cystene
+
+**Cystene CLI + MCP** — scan your infrastructure from your terminal or your AI assistant.
+
+One `pip install` ships three entry points over a single shared core:
+
+- **`cystene`** — the CLI. `cystene scan <url>` runs the engines and prints ranked findings.
+- **`cystene-mcp`** — the MCP server over stdio (Claude Desktop / Claude Code / Cursor).
+- **`cystene-mcp-http`** — the MCP server over HTTP + OAuth (remote, `mcp.cystene.com`).
+
+## Install
+
+```bash
+pip install cystene
+# or:  uv tool install cystene
+cystene --help
+```
+
+## Login
+
+```bash
+cystene login            # browser (OAuth device flow)
+cystene login --basic    # email/password in the terminal (headless / CI)
+cystene status           # show current auth status
+```
+
+Credentials are stored locally in `~/.cystene/credentials.json` (chmod 600). Your
+password never reaches the AI — login happens in your browser or terminal.
+
+## Scan from the terminal
+
+```bash
+cystene scan https://app.example.com
+cystene scan https://app.example.com --engines web_scan,baas_scan,secret_scan
+cystene scan https://app.example.com --fail-on critical
+```
+
+`scan` finds or creates a target for the URL, runs the external engines, prints the
+findings ranked worst-first with severity + confidence, and exits non-zero when any
+finding is at or above `--fail-on` (default `high`) — drop it straight into CI:
+
+```yaml
+- run: pip install cystene && cystene login --basic <<< "$CYSTENE_EMAIL\n$CYSTENE_PASSWORD"
+- run: cystene scan "$DEPLOY_URL" --fail-on high
+```
+
+## Use from your AI assistant (MCP)
+
+After `cystene login`, wire the stdio server into your client:
+
+**Claude Code:**
+
+```bash
+claude mcp add cystene -- cystene-mcp
+```
+
+**Claude Desktop / Cursor** — add to the MCP config:
+
+```json
+{
+  "mcpServers": {
+    "cystene": { "command": "cystene-mcp" }
+  }
+}
+```
+
+Then ask: *"Scan https://app.example.com and show me the critical findings."*
+
+## Tools (MCP)
+
+| Group | Tools |
+|-------|-------|
+| **Context** | get_permissions, list_organizations, set_organization |
+| **Infrastructure** | list_scan_targets, create_scan_target |
+| **Execution** | scan, list_scan_templates, create_scan_template, start_scan, get_scan_job, list_scan_jobs |
+| **Discovery** | list_findings, get_finding, list_assets, get_dashboard, generate_report |
+
+## Security
+
+- Passwords never reach the AI — login happens in your browser or terminal.
+- Credentials stored locally in `~/.cystene/credentials.json` (chmod 600).
+- Automatic token refresh on expiry.
+- No destructive operations exposed over MCP.
+- All API validations, permissions, subscription gating, and audit logging apply.
+
+## Requirements
+
+- Python 3.12+
+- A [Cystene](https://www.cystene.com) account

cystene-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "cystene"
+version = "0.1.0"
+description = "Cystene CLI + MCP — scan your infrastructure from your terminal or your AI assistant"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Robert Radoslav", email = "43938206+rbtrsv@users.noreply.github.com" }
+]
+requires-python = ">=3.12"
+keywords = ["cystene", "security", "scanner", "pentest", "espm", "mcp", "cli", "ai", "claude", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Topic :: Security",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+# Pinned to the latest stable releases on PyPI (2026-07-15), NOT the older
+# versions the finpy/nexotype reference packages ship — we build against current.
+dependencies = [
+    "click>=8.4.2",
+    "fastmcp>=3.4.4",
+    "httpx>=0.28.1",
+]
+
+[project.urls]
+Homepage = "https://www.cystene.com"
+Documentation = "https://www.cystene.com"
+"PyPI" = "https://pypi.org/project/cystene/"
+
+[project.scripts]
+cystene = "cystene.cli:main"                    # human CLI — cystene scan <url>, login, status
+cystene-mcp = "cystene.server:main"             # stdio — Claude Desktop/Code/Cursor
+cystene-mcp-http = "cystene.server:main_http"   # HTTP + OAuth — claude.ai / remote clients (mcp.cystene.com)
+
+[build-system]
+requires = ["uv_build>=0.8.15,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+]
+
+# Project test convention: filenames suffixed with `_test.py` (NOT prefixed
+# `test_*`). Matches the server's `apps/{module}/tests/` layout. Async tests
+# auto-await via asyncio_mode = "auto" — no @pytest.mark.asyncio needed.
+[tool.pytest.ini_options]
+python_files = ["*_test.py"]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+# Pylance/Pyright can't infer the src/ layout from the uv editable install
+# (`.pth` file). Pointing `extraPaths` at `src` makes `from cystene...`
+# resolve in the IDE without affecting runtime — pytest already finds it
+# via the installed package.
+[tool.pyright]
+include = ["src", "tests"]
+extraPaths = ["src"]
+venvPath = "."
+venv = ".venv"

cystene-0.1.0/src/cystene/__init__.py

@@ -0,0 +1 @@
+# Hello from cystene — CLI (`cystene`) + MCP (`cystene-mcp`) over one shared core.

cystene-0.1.0/src/cystene/_scan_flow.py

@@ -0,0 +1,211 @@
+"""
+Cystene — scan orchestration (shared core for CLI and MCP).
+
+The one-command `scan <url>` flow: find-or-create a ScanTarget for the URL,
+find-or-create a reusable "CLI scan" template, start the job, poll until it
+finishes, then return the findings. Used by BOTH the CLI `scan` command (via
+asyncio.run) and the MCP `scan` tool (awaited directly) — one implementation,
+zero duplication.
+"""
+
+import asyncio
+import ipaddress
+import time
+
+from .config import SCAN_MAX_WAIT, SCAN_POLL_INTERVAL
+from .client import CysteneClient
+
+# Default engine set for `scan <url>`: every external scanner that needs NEITHER
+# credentials NOR active-scan consent. Excludes active_web_scan (consent),
+# access_control_scan (creds+consent), host/cloud/ad_audit (creds), mobile_scan (upload).
+# MAINTENANCE (re-verify when a scanner is added/renamed): mirror the SCANNERS keys in
+# server/apps/cybersecurity/scanners/__init__.py — HOW TO CHECK: grep that file's dict keys.
+DEFAULT_ENGINES = [
+    "port_scan", "dns_enum", "ssl_check", "web_scan", "vuln_scan", "api_scan",
+    "password_audit", "baas_scan", "secret_scan", "client_auth_scan",
+    "subdomain_takeover_scan", "dependency_scan", "cms_scan",
+]
+
+# Reusable template name the CLI/MCP scan flow creates per target — kept idempotent.
+CLI_TEMPLATE_NAME = "CLI scan"
+
+# Severity ordering — drives the exit-code gate and worst-first sorting.
+SEVERITY_RANK = {"info": 0, "low": 1, "medium": 2, "high": 3, "critical": 4}
+
+# Job lifecycle states that mean the poll loop can stop.
+TERMINAL_STATUSES = {"completed", "failed", "cancelled"}
+
+
+# ==========================================
+# Target + template resolution (find-or-create)
+# ==========================================
+
+def infer_target_type(value: str) -> str:
+    """Classify a user-supplied target into a TargetType value.
+    URL if it carries a scheme; IP if the host parses as an address; else a bare domain."""
+    v = value.strip()
+    if "://" in v:
+        return "url"
+    host = v.split("/")[0].split(":")[0]
+    try:
+        ipaddress.ip_address(host)
+        return "ip"
+    except ValueError:
+        return "domain"
+
+
+def _same_value(a: str | None, b: str) -> bool:
+    """Case-insensitive exact match of two target values."""
+    return (a or "").strip().lower() == b.strip().lower()
+
+
+def _engine_set(scan_types: str | None) -> set[str]:
+    """Parse a comma-separated scan_types string into a normalized engine set.
+    Why a set: template reuse must be order-insensitive — "web_scan,baas_scan" and
+    "baas_scan,web_scan" are the same template, not two."""
+    return {e.strip() for e in (scan_types or "").split(",") if e.strip()}
+
+
+async def find_or_create_target(client: CysteneClient, value: str) -> dict:
+    """Return an existing ScanTarget matching `value`, or create one.
+    Why find-first: on the FREE tier (1 target) and on repeat scans we reuse the
+    same target instead of piling up rows."""
+    listing = await client.get("/cybersecurity/scan-targets/")
+    for target in listing.get("data") or []:
+        if _same_value(target.get("target_value"), value):
+            return target
+    created = await client.post(
+        "/cybersecurity/scan-targets/",
+        {"name": value, "target_type": infer_target_type(value), "target_value": value},
+    )
+    return created["data"]
+
+
+async def find_or_create_template(client: CysteneClient, target_id: int, engines: list[str]) -> dict:
+    """Return the reusable "CLI scan" template for this target with the requested
+    engine set, or create it. Idempotent per (target, engine-set) regardless of order."""
+    requested = _engine_set(",".join(engines))
+    scan_types = ",".join(engines)
+    listing = await client.get("/cybersecurity/scan-templates/")
+    for tpl in listing.get("data") or []:
+        if (
+            tpl.get("target_id") == target_id
+            and tpl.get("name") == CLI_TEMPLATE_NAME
+            and _engine_set(tpl.get("scan_types")) == requested
+        ):
+            return tpl
+    created = await client.post(
+        "/cybersecurity/scan-templates/",
+        {"target_id": target_id, "name": CLI_TEMPLATE_NAME, "scan_types": scan_types},
+    )
+    return created["data"]
+
+
+# ==========================================
+# Job start + poll + findings
+# ==========================================
+
+async def start_scan_job(client: CysteneClient, target_id: int, template_id: int) -> dict:
+    """Start a scan job (returns immediately with status=pending).
+    Note: /scan-jobs/start takes its arguments as query params, not a JSON body."""
+    started = await client.post(
+        "/cybersecurity/scan-jobs/start",
+        params={"target_id": target_id, "template_id": template_id},
+    )
+    return started["data"]
+
+
+async def poll_job(client: CysteneClient, job_id: int, on_poll=None) -> dict:
+    """Poll GET /scan-jobs/{id} until it reaches a terminal status or SCAN_MAX_WAIT.
+    `on_poll(job)` fires after each poll so callers can show live progress. On
+    timeout the job keeps running server-side; we return the last snapshot."""
+    deadline = time.monotonic() + SCAN_MAX_WAIT
+    while True:
+        job = (await client.get(f"/cybersecurity/scan-jobs/{job_id}"))["data"]
+        if on_poll:
+            on_poll(job)
+        if job.get("status") in TERMINAL_STATUSES or time.monotonic() >= deadline:
+            return job
+        await asyncio.sleep(SCAN_POLL_INTERVAL)
+
+
+async def get_findings(client: CysteneClient, job_id: int, severity: str | None = None) -> list[dict]:
+    """List findings for one scan job, optionally filtered by severity."""
+    params: dict = {"scan_job_id": job_id}
+    if severity:
+        params["severity"] = severity
+    resp = await client.get("/cybersecurity/findings/", params=params)
+    return resp.get("data") or []
+
+
+async def run_scan(client: CysteneClient, value: str, engines: list[str] | None = None, on_event=None) -> dict:
+    """Full `scan <url>` orchestration. Returns {target, template, job, findings}.
+    `on_event(name, payload)` fires at each stage (target / template / job_started /
+    poll) for live CLI progress; MCP passes None (no streaming)."""
+    engines = engines or DEFAULT_ENGINES
+    emit = on_event or (lambda *_: None)
+
+    target = await find_or_create_target(client, value)
+    emit("target", target)
+    template = await find_or_create_template(client, target["id"], engines)
+    emit("template", template)
+    job = await start_scan_job(client, target["id"], template["id"])
+    emit("job_started", job)
+    job = await poll_job(client, job["id"], on_poll=lambda j: emit("poll", j))
+    findings = await get_findings(client, job["id"])
+    return {"target": target, "template": template, "job": job, "findings": findings}
+
+
+# ==========================================
+# Rendering + exit-code gate (shared by CLI and MCP)
+# ==========================================
+
+def sort_findings(findings: list[dict]) -> list[dict]:
+    """Worst severity first, then alphabetically by title."""
+    return sorted(
+        findings,
+        key=lambda f: (-SEVERITY_RANK.get(f.get("severity", "info"), 0), f.get("title", "")),
+    )
+
+
+def worst_severity_rank(findings: list[dict]) -> int:
+    """Highest severity rank across findings, or -1 when there are none."""
+    return max((SEVERITY_RANK.get(f.get("severity", "info"), 0) for f in findings), default=-1)
+
+
+def should_fail(findings: list[dict], fail_on: str) -> bool:
+    """True when any finding is at or above the `fail_on` severity — drives exit codes/CI."""
+    threshold = SEVERITY_RANK.get(fail_on, SEVERITY_RANK["high"])
+    return worst_severity_rank(findings) >= threshold
+
+
+def render_scan_result(result: dict) -> str:
+    """Plain-text report of a scan result — printed by the CLI and returned by the
+    MCP `scan` tool. One renderer, no ANSI (keeps it LLM-friendly for MCP)."""
+    job = result["job"]
+    target = result["target"]
+    findings = sort_findings(result["findings"])
+
+    lines = [
+        f"Scanned {target.get('target_value')}  [job #{job.get('id')}]  status={job.get('status')}",
+        (
+            f"CRITICAL {job.get('critical_count', 0)}   HIGH {job.get('high_count', 0)}   "
+            f"MEDIUM {job.get('medium_count', 0)}   LOW {job.get('low_count', 0)}   "
+            f"INFO {job.get('info_count', 0)}"
+        ),
+    ]
+    if findings:
+        lines.append("")
+        for f in findings:
+            sev = (f.get("severity") or "info").upper()
+            conf = f.get("confidence") or "confirmed"
+            lines.append(f"[{sev} · {conf}] {f.get('title')}  ({f.get('finding_type')})")
+    else:
+        lines.append("")
+        lines.append("No findings.")
+
+    score = job.get("security_score")
+    if score is not None:
+        lines.append("")
+        lines.append(f"Security score: {score}/100")
+    return "\n".join(lines)