cipher-mcp-scan 0.1.0__tar.gz

cipher_mcp_scan-0.1.0/PKG-INFO

@@ -0,0 +1,367 @@
+Metadata-Version: 2.4
+Name: cipher-mcp-scan
+Version: 0.1.0
+Summary: Local security scan CLI for Cipher checks
+Author: Cipher
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests<3.0.0,>=2.31.0
+
+# Cipher
+
+Cipher is a local static-analysis scanner for security and supply-chain review. It inspects a project path and runs four focused checks:
+
+1. Authentication
+2. Over-Privilege
+3. CVE Lookup
+4. Typosquatting / Shadowing
+
+The goal of this repository is not to guess at security problems. It is to produce high-signal findings from concrete code and manifest evidence, then present them in a format that is useful for triage.
+
+## Installing the CLI package
+
+This repo can also be installed as a local CLI package:
+
+```bash
+pip install -e .
+cipher-scan . --fail-on high
+```
+
+The package is intentionally local-path only for v0.1: it scans the checked-out repository on disk, without any Render, Ollama, or remote download dependency.
+
+Use `--fail-on none` when you want a report-only run without a failing exit code.
+
+### Example local usage
+
+```bash
+cipher-scan .
+cipher-scan . --fail-on high --format json
+cipher-scan . --fail-on high --output cipher-scan-report.json
+```
+
+Private repositories work the same way as any other local repo: use GitHub Actions or a local checkout, then scan the checked-out path with `cipher-scan .`.
+
+## What This Repository Contains
+
+At the top level, Cipher has a very small shape:
+
+```text
+s:\Cipher
+├── checks/
+├── main/
+├── test/
+├── run_checks.py
+└── README.md
+```
+
+The important part is the `checks/` package. Each subpackage owns one security analysis area and exposes a public `scan()` interface. `run_checks.py` is the simple combined runner that executes all four checks in order for a local project path.
+
+## System Architecture
+
+The overall flow is intentionally simple.
+
+```mermaid
+flowchart TD
+    A[User provides local project path] --> B[run_checks.py]
+    B --> C[AuthenticationCheck]
+    B --> D[OverPrivilegeCheck]
+    B --> E[CVELookupCheck]
+    B --> F[TyposquattingCheck]
+
+    C --> G[Findings]
+    D --> G
+    E --> G
+    F --> G
+
+    G --> H[Readable console summary]
+```
+
+The combined runner does not try to interpret findings. It simply calls each check, catches errors per check, and prints a clean summary so one failure does not stop the rest of the scan.
+
+## Why The Architecture Looks This Way
+
+The design is deliberately modular.
+
+- Each check can be tested and improved independently.
+- Each check has its own data model assumptions and heuristics.
+- The runner remains small and stable even if one security area evolves.
+- A failure in one analysis path does not block the others.
+
+That separation matters because the four checks solve different problems:
+
+- Authentication looks for missing guards on sensitive handlers.
+- Over-Privilege looks for excessive capabilities and dangerous combinations.
+- CVE Lookup looks for vulnerable dependencies in manifests and lockfiles.
+- Typosquatting looks for suspicious near-matches and tool-name shadowing.
+
+## How A Scan Works
+
+The scan lifecycle is the same at a high level for all checks:
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant R as run_checks.py
+    participant C as Check implementation
+    participant O as Output
+
+    U->>R: Provide project path
+    R->>C: scan(project_root)
+    C->>C: Discover files and build context
+    C->>C: Apply rules / heuristics
+    C->>C: Return findings
+    R->>O: Print findings and summary
+```
+
+Each check follows that same pattern, but the internal analysis differs.
+
+## Check Overview
+
+### 1) Authentication Check
+
+The Authentication Check scans source code for security-sensitive entry points that appear to be exposed without a clear authentication guard.
+
+What it looks for:
+
+- MCP-style tool handlers
+- Route handlers that appear to do privileged work
+- Weak secret defaults and fail-open secret checks
+- Empty allowlists and risky CORS-style trust patterns
+- Non-loopback service bindings without a visible auth gate
+- Inconsistent auth enforcement across sibling routes
+
+Architecture view:
+
+```mermaid
+flowchart LR
+    A[Source files] --> B[Parser / AST extraction]
+    B --> C[Auth signal detector]
+    C --> D[Implementation validator]
+    D --> E[Security scorer]
+    E --> F[Finding]
+```
+
+The important idea is that the module does not rely on a single string match. It combines structure, decorators, routes, imports, and auth-related evidence before emitting a finding.
+
+### 2) Over-Privilege Check
+
+The Over-Privilege Check looks at tool and capability declarations, especially MCP configuration, and asks a simple question: does this tool request more power than it needs?
+
+What it looks for:
+
+- filesystem read/write/execute capabilities
+- network access
+- credential access
+- database access
+- system or process privileges
+- dangerous capability combinations such as data exfiltration or privilege escalation chains
+
+Architecture view:
+
+```mermaid
+flowchart LR
+    A[mcp.json / capability config] --> B[Capability extractor]
+    B --> C[Dangerous combo detector]
+    C --> D[Least-privilege evaluator]
+    D --> E[Risk calculator]
+    E --> F[Finding]
+```
+
+This check is policy-driven. The capability taxonomy and combo table define the security meaning, while the evaluator turns those declarations into findings and severity.
+
+### 3) CVE Lookup Check
+
+The CVE Lookup Check is a dependency vulnerability scan for supported manifests and lockfiles.
+
+Supported inputs:
+
+- `requirements.txt` and `requirements-*.txt`
+- `pyproject.toml`
+- `package.json`
+- `package-lock.json`
+- `poetry.lock`
+
+Architecture view:
+
+```mermaid
+flowchart LR
+    A[Dependency manifests] --> B[Dependency extractor]
+    B --> C[Version resolution / lockfile hints]
+    C --> D[OSV-compatible lookup]
+    D --> E[Cache]
+    D --> F[Finding builder]
+    E --> D
+    F --> G[Aggregated findings]
+```
+
+This check is designed to stay offline-safe when network lookup is unavailable. It also keeps the output low-noise by aggregating by package and merging vulnerability identifiers into a single finding when possible.
+
+### 4) Typosquatting / Shadowing Check
+
+The Typosquatting Check scans package names and MCP tool names for suspicious near-matches.
+
+What it looks for:
+
+- package names that closely resemble known popular package names
+- MCP tool names that closely resemble known tool names
+- duplicate tool names that can shadow one another across configs
+
+Architecture view:
+
+```mermaid
+flowchart LR
+    A[Manifest and MCP names] --> B[Name extractor]
+    B --> C[Similarity detector]
+    B --> D[Shadowing detector]
+    C --> E[Finding builder]
+    D --> E
+    E --> F[Offline-safe findings]
+```
+
+This check is also offline-safe. It works from a local trusted-name catalog and local project files, not from external registry queries.
+
+## Combined Runner
+
+`run_checks.py` is the main entry point for demo use.
+
+What it does:
+
+- accepts one local project path argument
+- runs the four checks in order
+- prints each check name and finding count
+- prints each finding as `severity | title | file_path`
+- catches errors per check and continues scanning the rest
+
+Example:
+
+```powershell
+python run_checks.py .\test\Cipher-demo-main
+```
+
+That runner is intentionally small. It is a presentation layer, not a fifth scanner.
+
+## Repository Map
+
+```mermaid
+flowchart TD
+    A[Repository root] --> B[checks/]
+    A --> C[main/]
+    A --> D[test/]
+    A --> E[run_checks.py]
+
+    B --> B1[authentication/]
+    B --> B2[over_privilege/]
+    B --> B3[cve_lookup/]
+    B --> B4[typosquatting/]
+
+    B1 --> B1a[auth_check.py]
+    B1 --> B1b[self_test.py]
+    B2 --> B2a[over_privilege_check.py]
+    B2 --> B2b[self_test.py]
+    B3 --> B3a[cve_check.py]
+    B3 --> B3b[self_test.py]
+    B4 --> B4a[typosquatting_check.py]
+    B4 --> B4b[self_test.py]
+```
+
+### Directory Roles
+
+- `checks/` contains the actual analysis logic.
+- `main/` contains shared project data and support code.
+- `test/` contains a vulnerable demo repository that the checks can scan.
+- `run_checks.py` is the combined CLI runner.
+
+## Output Philosophy
+
+Cipher is designed for triage, not for maximum noise.
+
+That means:
+
+- findings should be explainable from the evidence shown
+- duplicate emissions should be reduced when they do not add value
+- remediation should point toward an obvious next action
+- severity should reflect the strength of the signal, not just the existence of a match
+
+In practice, a useful finding usually includes:
+
+- severity
+- title
+- file path
+- evidence
+- remediation guidance
+
+## Example End-to-End Scan
+
+If you scan the bundled demo target, the runner will print a grouped summary like this:
+
+```text
+Scanning: S:\Cipher\test\Cipher-demo-main
+
+== AuthenticationCheck ==
+Findings: 4
+- high | Missing authentication for sensitive MCP tool handler | server.py
+
+== OverPrivilegeCheck ==
+Findings: 6
+- high | Dangerous combination: Data Exfiltration | S:\Cipher\test\Cipher-demo-main\mcp.json
+
+== CVELookupCheck ==
+Findings: 4
+- critical | Known npm dependency vulnerability: axios | S:\Cipher\test\Cipher-demo-main\package.json
+
+== TyposquattingCheck ==
+Findings: 2
+- medium | Potential package name typosquatting | S:\Cipher\test\Cipher-demo-main\package.json
+```
+
+The exact findings depend on the target project, but the format stays the same.
+
+## Working With The Individual Checks
+
+Each check keeps the same public scan interface.
+
+```python
+from checks.authentication.auth_check import AuthenticationCheck
+from checks.over_privilege.over_privilege_check import OverPrivilegeCheck
+from checks.cve_lookup.cve_check import CVELookupCheck
+from checks.typosquatting.typosquatting_check import TyposquattingCheck
+
+root = r"S:\Cipher\test\Cipher-demo-main"
+
+auth_findings = AuthenticationCheck(root).scan()
+priv_findings = OverPrivilegeCheck(root).scan()
+cve_findings = CVELookupCheck(root).scan()
+typo_findings = TyposquattingCheck(root).scan()
+```
+
+That interface consistency is important because it lets the combined runner stay simple.
+
+## Testing
+
+The repository includes package-level self-tests for each check. The tests are designed to protect the behavior of the public scan interface and the project-specific heuristics.
+
+Typical commands:
+
+```powershell
+python -m unittest checks.authentication.self_test
+python -m unittest checks.over_privilege.self_test
+python -m unittest checks.cve_lookup.self_test
+python -m unittest checks.typosquatting.self_test
+```
+
+## Practical Notes
+
+- The scanner works on a local path only.
+- The CVE check prefers exact version evidence and can fall back to cache behavior when needed.
+- The typosquatting check is offline-safe and uses a local trusted-name set.
+- The runner is intentionally minimal so it can be used in demos without extra setup.
+
+## Short Version
+
+If you want the shortest mental model possible, think of Cipher like this:
+
+1. Point it at a local project directory.
+2. It inspects source files and manifests.
+3. Each check produces security findings from a different angle.
+4. The combined runner prints the result in a readable, triage-friendly summary.