eyalsec-mcp 0.1.0__tar.gz

eyalsec_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

eyalsec_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EyalSec
+
+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.

eyalsec_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: eyalsec-mcp
+Version: 0.1.0
+Summary: MCP server for reading your EyalSec security events, machines, runs and rules from an AI assistant.
+Project-URL: Homepage, https://eyalsec.com
+Project-URL: Documentation, https://eyalsec.com/docs/api
+Project-URL: Source, https://github.com/EyalSec/eyalsec-mcp
+Project-URL: Issues, https://github.com/EyalSec/eyalsec-mcp/issues
+Project-URL: Pricing, https://eyalsec.com/pricing
+Project-URL: Book a demo, https://eyalsec.com/contact
+Author-email: EyalSec <support@eyalsec.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: application security,claude,cursor,es-python,eyalsec,mcp,mcp server,model context protocol,security events,taint tracking
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic>=2.7
+Provides-Extra: test
+Requires-Dist: anyio>=4; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# EyalSec MCP server
+
+Ask your AI assistant about your EyalSec account in plain words: "what critical events came in since Monday?", "show me the full trace for event 90210", "which machines need an update?". This server gives Claude, Cursor and any other MCP client read access to your events, machines, runs and rules through the [EyalSec API](https://eyalsec.com/docs/api), so the assistant you already use for code review can also help you triage what EyalSec found.
+
+<!-- mcp-name: io.github.EyalSec/eyalsec-mcp -->
+
+EyalSec follows untrusted data (requests, files, environment variables and more) through your running program and reports when it reaches a risky operation: a SQL query, a shell command, deserialization, a file path. Each event names the operation, the line of code, the value it received and where the untrusted part came from. This server reads those events; it never changes anything on your account.
+
+## What you need
+
+- An EyalSec account and an API key. Create the key on your dashboard under **Settings > API access**. A **read-only key** is all this server needs, and it is the one we recommend: see [API keys](https://eyalsec.com/docs/api-keys).
+- Python 3.10 or newer, or [`uv`](https://docs.astral.sh/uv/), which runs the server without a separate install.
+
+No account yet? [Book a live demo](https://eyalsec.com/contact) and we will set one up with you. Pricing is at [eyalsec.com/pricing](https://eyalsec.com/pricing).
+
+## Set it up
+
+The server speaks MCP over stdio. Your client starts it with `uvx eyalsec-mcp` (or `eyalsec-mcp` after `pipx install eyalsec-mcp`) and passes the key in the environment.
+
+### Claude Code
+
+```bash
+claude mcp add eyalsec -e EYALSEC_API_KEY=es2_your_read_only_key -- uvx eyalsec-mcp
+```
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json` (Settings > Developer > Edit Config), then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "eyalsec": {
+      "command": "uvx",
+      "args": ["eyalsec-mcp"],
+      "env": {
+        "EYALSEC_API_KEY": "es2_your_read_only_key"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add the same block to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "eyalsec": {
+      "command": "uvx",
+      "args": ["eyalsec-mcp"],
+      "env": {
+        "EYALSEC_API_KEY": "es2_your_read_only_key"
+      }
+    }
+  }
+}
+```
+
+### Any other MCP client
+
+Run `uvx eyalsec-mcp` as a stdio server with `EYALSEC_API_KEY` set. To check the key before wiring it into a client:
+
+```bash
+EYALSEC_API_KEY=es2_your_read_only_key uvx eyalsec-mcp --check
+```
+
+It calls the API once and prints the account it reached, the key's scope and the number of machines.
+
+### Settings
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `EYALSEC_API_KEY` | yes | Your API key, from **Settings > API access**. Read-only is enough. |
+| `EYALSEC_URL` | no | Your EyalSec address. Defaults to `https://eyalsec.com`; set it only if your account lives on another domain. Must be `https://`. |
+
+## What it can do
+
+Every tool is a read. The server has no code path that adds, changes or deletes anything, so even a full-access key cannot be used to write through it.
+
+| Tool | What it answers |
+|---|---|
+| `search_events` | Your events, newest or most severe first, with the events page's filters: product, severity, dates, machine, taint source, impact class, label, sink pattern, run, and the advanced condition builder. Follows the API's paging for you. |
+| `get_event` | One event in full: stack trace, where the data came in, where the value was created, nearby source code when the machine sends it, your note, and the runs that produced it. |
+| `event_stats` | The dashboard summary: totals, the last hour, day and week, top event types and a 14-day timeline. |
+| `event_counts` | How many events each product's list holds, live versus suppressed, and the count toward your monthly quota. |
+| `list_event_names` | The distinct sink labels across your events, handy for building a filter. |
+| `event_map` | The es-python events as a graph: sources, the files data was read from, and the operations it reached. |
+| `list_runs` | The program invocations behind your events, with their command lines (secrets masked). |
+| `ci_findings` | What runs on one machine reported since a moment, counted by severity, with which findings are new. |
+| `list_machines` | Every machine: status, OS target, product, installed and newest build, and whether an update is waiting. |
+| `supported_targets` | The Linux distributions, architectures and Python versions es-python installs on. |
+| `list_rules`, `list_filters`, `get_taint_settings`, `get_event_uniqueness`, `list_rule_templates` | How your account and each machine are configured. |
+| `list_labels`, `list_saved_searches` | Your triage labels and saved searches. |
+| `get_account`, `list_activity` | Your profile and limits, your key's scope and expiry (never the key), setup progress, and the activity log. |
+
+Some things to try:
+
+- "Summarize this week's critical and high events by machine."
+- "Open the newest SQL injection event and explain the path from the request to the query."
+- "Which runs of `app.py` produced command-injection events yesterday?"
+- "Do any machines have an update waiting or an install stuck in pending?"
+
+## Safety notes
+
+- **Events contain untrusted text.** A value that reached a sink, a stack trace or a command line came from a monitored program and its inputs, which can include text an attacker wrote. The server tells the assistant to treat it as data, not instructions; keep human review on anything the assistant proposes to do with it.
+- **Use a read-only key.** It can read everything this server reads and nothing more. A key can also carry an expiry date.
+- **The key stays with you.** It is read from the environment, sent only to your EyalSec address over HTTPS, and never returned by any tool. Plain HTTP is refused except to `localhost`.
+- The API's [rate limits](https://eyalsec.com/docs/api#rate-limits) apply. `search_events` reads at most 10 pages per call and hands back a cursor for the rest.
+
+## Development
+
+```bash
+git clone https://github.com/EyalSec/eyalsec-mcp && cd eyalsec-mcp
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[test]'
+pytest
+```
+
+The tests run against a fake API. To also run one read-only pass against your own account, set `EYALSEC_LIVE=1` and `EYALSEC_API_KEY`.
+
+## Help
+
+Questions and bug reports are welcome in [issues](https://github.com/EyalSec/eyalsec-mcp/issues), or write to support@eyalsec.com. Please send security reports to security@eyalsec.com rather than a public issue.
+
+## License
+
+MIT. See [LICENSE](LICENSE). The license covers this MCP server; your EyalSec account is governed by the [EyalSec terms](https://eyalsec.com/legal/terms).

eyalsec_mcp-0.1.0/README.md

@@ -0,0 +1,130 @@
+# EyalSec MCP server
+
+Ask your AI assistant about your EyalSec account in plain words: "what critical events came in since Monday?", "show me the full trace for event 90210", "which machines need an update?". This server gives Claude, Cursor and any other MCP client read access to your events, machines, runs and rules through the [EyalSec API](https://eyalsec.com/docs/api), so the assistant you already use for code review can also help you triage what EyalSec found.
+
+<!-- mcp-name: io.github.EyalSec/eyalsec-mcp -->
+
+EyalSec follows untrusted data (requests, files, environment variables and more) through your running program and reports when it reaches a risky operation: a SQL query, a shell command, deserialization, a file path. Each event names the operation, the line of code, the value it received and where the untrusted part came from. This server reads those events; it never changes anything on your account.
+
+## What you need
+
+- An EyalSec account and an API key. Create the key on your dashboard under **Settings > API access**. A **read-only key** is all this server needs, and it is the one we recommend: see [API keys](https://eyalsec.com/docs/api-keys).
+- Python 3.10 or newer, or [`uv`](https://docs.astral.sh/uv/), which runs the server without a separate install.
+
+No account yet? [Book a live demo](https://eyalsec.com/contact) and we will set one up with you. Pricing is at [eyalsec.com/pricing](https://eyalsec.com/pricing).
+
+## Set it up
+
+The server speaks MCP over stdio. Your client starts it with `uvx eyalsec-mcp` (or `eyalsec-mcp` after `pipx install eyalsec-mcp`) and passes the key in the environment.
+
+### Claude Code
+
+```bash
+claude mcp add eyalsec -e EYALSEC_API_KEY=es2_your_read_only_key -- uvx eyalsec-mcp
+```
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json` (Settings > Developer > Edit Config), then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "eyalsec": {
+      "command": "uvx",
+      "args": ["eyalsec-mcp"],
+      "env": {
+        "EYALSEC_API_KEY": "es2_your_read_only_key"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add the same block to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "eyalsec": {
+      "command": "uvx",
+      "args": ["eyalsec-mcp"],
+      "env": {
+        "EYALSEC_API_KEY": "es2_your_read_only_key"
+      }
+    }
+  }
+}
+```
+
+### Any other MCP client
+
+Run `uvx eyalsec-mcp` as a stdio server with `EYALSEC_API_KEY` set. To check the key before wiring it into a client:
+
+```bash
+EYALSEC_API_KEY=es2_your_read_only_key uvx eyalsec-mcp --check
+```
+
+It calls the API once and prints the account it reached, the key's scope and the number of machines.
+
+### Settings
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `EYALSEC_API_KEY` | yes | Your API key, from **Settings > API access**. Read-only is enough. |
+| `EYALSEC_URL` | no | Your EyalSec address. Defaults to `https://eyalsec.com`; set it only if your account lives on another domain. Must be `https://`. |
+
+## What it can do
+
+Every tool is a read. The server has no code path that adds, changes or deletes anything, so even a full-access key cannot be used to write through it.
+
+| Tool | What it answers |
+|---|---|
+| `search_events` | Your events, newest or most severe first, with the events page's filters: product, severity, dates, machine, taint source, impact class, label, sink pattern, run, and the advanced condition builder. Follows the API's paging for you. |
+| `get_event` | One event in full: stack trace, where the data came in, where the value was created, nearby source code when the machine sends it, your note, and the runs that produced it. |
+| `event_stats` | The dashboard summary: totals, the last hour, day and week, top event types and a 14-day timeline. |
+| `event_counts` | How many events each product's list holds, live versus suppressed, and the count toward your monthly quota. |
+| `list_event_names` | The distinct sink labels across your events, handy for building a filter. |
+| `event_map` | The es-python events as a graph: sources, the files data was read from, and the operations it reached. |
+| `list_runs` | The program invocations behind your events, with their command lines (secrets masked). |
+| `ci_findings` | What runs on one machine reported since a moment, counted by severity, with which findings are new. |
+| `list_machines` | Every machine: status, OS target, product, installed and newest build, and whether an update is waiting. |
+| `supported_targets` | The Linux distributions, architectures and Python versions es-python installs on. |
+| `list_rules`, `list_filters`, `get_taint_settings`, `get_event_uniqueness`, `list_rule_templates` | How your account and each machine are configured. |
+| `list_labels`, `list_saved_searches` | Your triage labels and saved searches. |
+| `get_account`, `list_activity` | Your profile and limits, your key's scope and expiry (never the key), setup progress, and the activity log. |
+
+Some things to try:
+
+- "Summarize this week's critical and high events by machine."
+- "Open the newest SQL injection event and explain the path from the request to the query."
+- "Which runs of `app.py` produced command-injection events yesterday?"
+- "Do any machines have an update waiting or an install stuck in pending?"
+
+## Safety notes
+
+- **Events contain untrusted text.** A value that reached a sink, a stack trace or a command line came from a monitored program and its inputs, which can include text an attacker wrote. The server tells the assistant to treat it as data, not instructions; keep human review on anything the assistant proposes to do with it.
+- **Use a read-only key.** It can read everything this server reads and nothing more. A key can also carry an expiry date.
+- **The key stays with you.** It is read from the environment, sent only to your EyalSec address over HTTPS, and never returned by any tool. Plain HTTP is refused except to `localhost`.
+- The API's [rate limits](https://eyalsec.com/docs/api#rate-limits) apply. `search_events` reads at most 10 pages per call and hands back a cursor for the rest.
+
+## Development
+
+```bash
+git clone https://github.com/EyalSec/eyalsec-mcp && cd eyalsec-mcp
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[test]'
+pytest
+```
+
+The tests run against a fake API. To also run one read-only pass against your own account, set `EYALSEC_LIVE=1` and `EYALSEC_API_KEY`.
+
+## Help
+
+Questions and bug reports are welcome in [issues](https://github.com/EyalSec/eyalsec-mcp/issues), or write to support@eyalsec.com. Please send security reports to security@eyalsec.com rather than a public issue.
+
+## License
+
+MIT. See [LICENSE](LICENSE). The license covers this MCP server; your EyalSec account is governed by the [EyalSec terms](https://eyalsec.com/legal/terms).

eyalsec_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "eyalsec-mcp"
+version = "0.1.0"
+description = "MCP server for reading your EyalSec security events, machines, runs and rules from an AI assistant."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "EyalSec", email = "support@eyalsec.com" }]
+keywords = [
+    "mcp", "model context protocol", "mcp server", "eyalsec", "es-python",
+    "application security", "security events", "taint tracking", "claude", "cursor",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+]
+dependencies = [
+    "mcp>=2.3,<3",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "anyio>=4"]
+
+[project.scripts]
+eyalsec-mcp = "eyalsec_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://eyalsec.com"
+Documentation = "https://eyalsec.com/docs/api"
+Source = "https://github.com/EyalSec/eyalsec-mcp"
+Issues = "https://github.com/EyalSec/eyalsec-mcp/issues"
+Pricing = "https://eyalsec.com/pricing"
+"Book a demo" = "https://eyalsec.com/contact"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/eyalsec_mcp"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/eyalsec_mcp", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]

eyalsec_mcp-0.1.0/src/eyalsec_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""EyalSec MCP server: read your EyalSec account from an AI assistant."""
+
+__version__ = "0.1.0"

eyalsec_mcp-0.1.0/src/eyalsec_mcp/__main__.py

@@ -0,0 +1,72 @@
+"""Command line entry point: `eyalsec-mcp` runs the server on stdio."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+from . import __version__
+from .client import API_KEY_ENV, URL_ENV, APIError, ConfigError, EyalSecClient
+
+
+async def _check() -> int:
+    """Call the API once with the configured key and say what it found.
+    Everything goes to stderr: on stdio, stdout belongs to the MCP protocol."""
+    try:
+        api = EyalSecClient()
+    except ConfigError as exc:
+        print(f"eyalsec-mcp: {exc}", file=sys.stderr)
+        return 2
+    try:
+        profile = await api.get("/api/account/")
+        key = await api.get("/api/account/apikey")
+        machines = await api.get("/api/get_all_machines/")
+    except (APIError, ConfigError) as exc:
+        print(f"eyalsec-mcp: {exc}", file=sys.stderr)
+        return 1
+    finally:
+        await api.aclose()
+    print(
+        f"eyalsec-mcp {__version__}: connected to {api.base_url} as {profile.get('username', '?')}; "
+        f"key scope {key.get('scope', '?')}; {len(machines.get('machines') or [])} machine(s).",
+        file=sys.stderr,
+    )
+    if key.get("scope") == "full":
+        print(
+            "eyalsec-mcp: this server only reads, so a read-only key is enough. "
+            "Consider generating one on Settings > API access.",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="eyalsec-mcp",
+        description="MCP server (stdio) for reading your EyalSec account: events, machines, runs and rules.",
+        epilog=f"Configuration: {API_KEY_ENV} (required, an API key from Settings > API access; "
+        f"a read-only key is enough) and {URL_ENV} (optional, default https://eyalsec.com).",
+    )
+    parser.add_argument("--version", action="version", version=f"eyalsec-mcp {__version__}")
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="call the API once with the configured key, report the result and exit",
+    )
+    args = parser.parse_args(argv)
+    if args.check:
+        sys.exit(asyncio.run(_check()))
+
+    from .server import create_server
+
+    try:
+        server = create_server()
+    except ConfigError as exc:
+        print(f"eyalsec-mcp: {exc}", file=sys.stderr)
+        sys.exit(2)
+    server.run("stdio")
+
+
+if __name__ == "__main__":
+    main()