Metadata-Version: 2.4
Name: emgena-scan
Version: 1.0.0
Summary: 100% Offline Static AST Security & SRE Incident Scanner for Python & Cloud Infrastructure
Author-email: Emgena AI Labs <engineering@emgena.com>
License: Apache-2.0
Project-URL: Homepage, https://emgena.com/trainingslager
Project-URL: Documentation, https://emgena.com/trainingslager#inspector
Project-URL: Repository, https://github.com/emgena/emgena-scan
Keywords: mcp,ast,static-analysis,sre,security,linter,cursor,claude,fastapi,redis
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# ⚡ Emgena Repo Scanner (`emgena-scan`)

> **100% Offline Static AST Security & SRE Incident Scanner for Python & Cloud Infrastructure.**  
> Zero Telemetry • Zero External Network Calls • Sub-0.15ms AST Analysis per Rule.

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
[![Zero Dependency](https://img.shields.io/badge/dependencies-0%20(pure%20stdlib)-brightgreen.svg)]()

---

## 🚀 Quickstart

Run instantly with **`uvx`** (zero install):
```bash
uvx emgena-scan .
```

Or install via **`pip`**:
```bash
pip install emgena-scan
emgena-scan .
```

Or run via Python module:
```bash
python -m emgena_scan .
```

---

## 🔍 What It Scans (Top-10 Production Incidents)

`emgena-scan` uses Python's standard library `ast` module to perform **real semantic static analysis** (not brittle regex matches). It catches:

1. **`RULE_FASTAPI_SYNC_CRYPTO` (CRITICAL)**: Synchronous CPU-bound hashing (`hmac`, `hashlib`, `bcrypt`) inside `async def` routes, blocking the main event loop.
2. **`RULE_BLOCKING_HTTP_IN_ASYNC` (CRITICAL)**: Synchronous `requests.get()` or `urllib` inside `async def`, causing thread starvation under load.
3. **`RULE_SQLALCHEMY_UNCLOSED_ASYNC_SESSION` (CRITICAL)**: Leaked database sessions without `async with` or generator contexts, exhausting the QueuePool in minutes.
4. **`RULE_REDIS_CLUSTER_CROSSSLOT` (HIGH)**: Multi-key Redis commands (`mget`, `pipeline`) lacking hash tags (`{...}`), causing immediate `CROSSSLOT` cluster crashes.
5. **`RULE_CELERY_SUBTASK_BLOCKING_GET` (HIGH)**: Calling `.get()` on subtasks inside Celery worker functions, causing cascading prefork deadlocks.
6. **`RULE_DOCKER_PRIVILEGED_SOCKET_MOUNT` (CRITICAL)**: Containers mounting `/var/run/docker.sock` with `privileged: true`, violating CIS Docker Benchmark 5.3.
7. **`RULE_SUBPROCESS_SHELL_TRUE_INJECTION` (CRITICAL)**: Invoking `subprocess` with `shell=True` and formatted string variables (CWE-78 Command Injection).
8. **`RULE_UNBOUNDED_DB_FETCHALL` (MEDIUM)**: Raw `.fetchall()` on SQL queries without limits or chunk iteration, risking OOMKilled crashes.
9. **`RULE_BARE_EXCEPT_PASS_SILENCING` (MEDIUM)**: `except: pass` silencing critical infrastructure exceptions.
10. **`RULE_THREADING_THREAD_UNBOUNDED_SPAWN` (HIGH)**: Unbounded `threading.Thread.start()` in API handlers without bounded threadpools.

---

## 💻 CLI Options

```bash
emgena-scan [OPTIONS] [PATH]

Arguments:
  PATH               Directory or file to scan (default: current directory)

Options:
  --json             Output machine-readable JSON for CI/CD pipelines
  --quiet, -q        Only output summary line and exit code
  --ignore-rules     Comma-separated list of rule IDs to ignore
  --version, -v      Show version
  --help, -h         Show help message
```

### Exit Codes for CI/CD
* `0`: Clean (no critical or high violations found)
* `1`: One or more violations detected
* `2`: Syntax or invocation error

---

## ⚡ Live Protection While You Code

Want to catch these issues in real time while typing in your editor?

Install the turnkey **Emgena SRE MCP Guards for Cursor IDE & Claude Desktop**:
👉 **[https://emgena.com/trainingslager](https://emgena.com/trainingslager)**

* 100% Offline stdio MCP Engine
* Real-time `<thought>` and AST diagnosis inside Cursor IDE
* Instant Vorher/Nachher remediation diffs with 0 syntax errors
