Metadata-Version: 2.4
Name: ekmire
Version: 2.0.4
Summary: Developer security platform — write-time, commit-time, and runtime protection
Author-email: Flux8Labs <team@flux8labs.com>
License: Proprietary
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.0
Requires-Dist: pathspec>=0.12

# ekmire

Developer security platform — write-time, commit-time, and runtime protection.

```bash
pip install ekmire
ekmire init
```

---

## Features

| Feature | Flag / Command | What it does |
|---|---|---|
| **Build Guard** (SAST) | `ekmire scan` | Detects secrets, injection, AI security risks in source code |
| **SCA** — dependency CVEs | `--deps` | Scans lockfiles against the OSV database for known CVEs |
| **Reachability analysis** | `--reachability` | Tags AST findings as reachable or not via call-graph analysis |
| **CycloneDX SBOM** | `--output cyclonedx` | Emits a CycloneDX 1.5 SBOM (SAST + SCA combined) |
| **SARIF** | `--output sarif` | Uploads findings to GitHub Code Scanning |
| **Dev Audit** | `ekmire dev-audit` | AI-powered security review of a file, dir, or staged diff |
| **MCP Audit** | `ekmire mcp audit` | Scans all IDE MCP server configs for exposure and poisoning risks |
| **Pre-commit hook** | `ekmire hook install` | Blocks commits with critical findings |

---

## Quick start

```bash
# Install
pip install ekmire

# First-run wizard: auth → scan → hook install
ekmire init

# Scan current directory
ekmire scan --deep .

# Also scan lockfiles for CVEs (SCA)
ekmire scan --deep . --deps

# Tag findings with reachability (AST engine, Python files)
ekmire scan --deep . --reachability

# Output SARIF for GitHub Code Scanning
ekmire scan --deep . --deps --output sarif > results.sarif

# Output CycloneDX SBOM (SAST + SCA)
ekmire scan --deep . --deps --output cyclonedx > sbom.cdx.json

# AI security review of a file or staged diff
ekmire dev-audit src/auth.py
ekmire dev-audit --diff

# Scan all IDE MCP configs
ekmire mcp audit
```

---

## scan command

```
ekmire scan [PATH] [OPTIONS]
```

| Option | Default | Description |
|---|---|---|
| `--deep` | off | Recursive scan without requiring git context |
| `--all` | off | Scan all files in working directory |
| `--deps` | off | Also scan lockfiles for CVEs via OSV (SCA) |
| `--reachability` | off | Tag AST findings with reachability analysis (slower) |
| `--output` | `text` | Output format: `text`, `json`, `sarif`, `cyclonedx` |
| `--fail-on` | none | Exit 1 if findings at or above this severity exist |

---

## Detection engines

### Engine A — regex (cross-language, fast)
Applied to raw file content. Detects hardcoded secrets, prompt injection patterns,
XSS risks, and misconfigured MCP server URLs.

### Engine B — AST (Python only)
Structural analysis using Python's `ast` module. Detects:
- `HARDCODED_SECRET_GENERIC` — high-entropy strings in secret-named variables
- `SQL_INJECTION_RISK` — f-strings or concatenation inside `execute()`
- `DANGEROUS_DESERIALISATION` — `pickle.loads()` / `marshal.loads()`
- `UNSAFE_YAML_LOAD` — `yaml.load()` without `SafeLoader`
- `COMMAND_INJECTION_RISK` — dynamic args to `subprocess.run()` / `os.system()`
- `MCP_TOOL_POISONING` — instruction-override language in MCP tool descriptions

With `--reachability`: each finding is tagged `[REACHABLE]` / `[NOT REACHABLE]`
based on a lightweight intra-file call-graph analysis.

### Engine C — SCA (lockfile scanning, network)
Parses package lockfiles and queries the OSV database (`api.osv.dev`) for known CVEs.

Supported lockfiles:
| Lockfile | Ecosystem |
|---|---|
| `requirements.txt` | PyPI |
| `Pipfile.lock` | PyPI |
| `poetry.lock` | PyPI |
| `package-lock.json` | npm |
| `yarn.lock` | npm |

SCA findings include: package name, installed version, fix version, CVE IDs,
and a copy-ready upgrade command (e.g. `pip install --upgrade requests==2.32.0`).

No source code is sent to any external service — only package name + version
is submitted to the public OSV API.

---

## Output formats

### `--output text` (default)
Rich terminal output with severity colours, reachability badges, fix commands,
suppression hints, and docs links.

### `--output json`
JSON array of findings. Each finding includes `rule_id`, `severity`, `file`, `line`,
`description`, `fix`, and (when available) `reachable`, `package`, `installed_version`,
`fix_version`, `cve_ids`.

### `--output sarif`
SARIF 2.1.0 for GitHub Code Scanning. Includes `help.text` (fix commands) and
`fixes` objects. Upload with `github/codeql-action/upload-sarif`.

### `--output cyclonedx`
CycloneDX 1.5 JSON SBOM. SCA findings appear as components + vulnerabilities;
SAST findings appear as code-level vulnerabilities.

---

## Suppression

To suppress a specific finding, add a comment on the line above (preferred) or inline:

```python
# ekmire-ignore:HARDCODED_SECRET_GENERIC
API_KEY = "..."  # this is a test value

token = get_token()  # ekmire-ignore:HARDCODED_SECRET_GENERIC
```

Suppressions are logged to your dashboard for review.

---

## CI / CD templates

Copy these into `.github/workflows/` in any repository:

| Template | Purpose |
|---|---|
| `templates/ekmire-sarif.yml` | SAST + SCA scan → GitHub Code Scanning (SARIF) |
| `templates/ekmire-cyclonedx.yml` | SAST + SCA → CycloneDX SBOM artifact |

---

## Authentication (optional)

Without authentication, ekmire works fully offline using the built-in rule bundle.
Authentication enables:
- Cloud rule bundle (updated threat feed)
- Dashboard event tracking
- AI Dev Audit (`ekmire dev-audit`)

```bash
ekmire auth login    # opens browser auth flow
ekmire auth status   # show current auth state
ekmire auth logout   # remove saved credentials
```

---

**Docs:** [ekmire.com/docs](https://ekmire.com/docs)  
**Dashboard:** [app.ekmire.com](https://app.ekmire.com)

© Flux8Labs 2026
