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
