# Codescan

> Agent-native code security review with MCP, structured findings, and practical pre-merge scanning workflows.

- **Type:** MCP server
- **Install:** `agentstack add mcp-hejiguang-codescan`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [HeJiguang](https://agentstack.voostack.com/s/hejiguang)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [HeJiguang](https://github.com/HeJiguang)
- **Source:** https://github.com/HeJiguang/codescan

## Install

```sh
agentstack add mcp-hejiguang-codescan
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# CodeScan

English | [简体中文](README.zh-CN.md)

AI-assisted code security scanning for files, repositories, Git diffs, and coding agents.  
Start with deterministic rules, use LLM analysis to deepen context, and expose the scanner through MCP and a Codex skill.

[](https://github.com/HeJiguang/codescan/actions/workflows/ci.yml)

## Quick Links

- [Why CodeScan](#why-codescan)
- [Who This Is For](#who-this-is-for)
- [Try It In 5 Minutes](#try-it-in-5-minutes)
- [Quick Start](#quick-start)
- [Use With Codex](#use-with-codex)
- [Example Output](#example-output)
- [Get Involved](#get-involved)
- [Roadmap](#roadmap)

## Why CodeScan

Many AI code scanners are just chat wrappers around pasted source files. They can sound smart, but the output is unstable, difficult to integrate, and hard to trust in real workflows.

CodeScan takes a stricter route:

- Start with deterministic rule-based signal
- Use LLM analysis to deepen context and explanation
- Force structured output instead of free-form blob parsing
- Deliver the same result model through CLI, reports, MCP tools, and Codex workflows

CodeScan focuses on review workflows where deterministic checks, structured findings, and agent integration matter.

## Who This Is For

CodeScan is most useful today for:

- developers who want a second security pass before merging code
- teams using Codex, Cursor, or Claude and wanting structured security tooling
- maintainers who want a lightweight repository triage tool without standing up a large platform
- contributors interested in security rules, AI-assisted analysis, or MCP-native developer tools

Today it works best as a review assistant and agent-native scanning layer rather than a full SAST platform.

## Try It In 5 Minutes

Start with these three items:

1. Browse the example fixture at [`examples/demo-vulnerable-app`](examples/demo-vulnerable-app)
2. Open the representative result at [`examples/sample-mcp-result.json`](examples/sample-mcp-result.json)
3. Read the visual walkthrough in [Example Output](docs/example-output.md)

For a local run:

```bash
pip install -e .
python -m codescan config --provider deepseek --api-key YOUR_API_KEY --model deepseek-chat
python -m codescan dir examples/demo-vulnerable-app --output demo-result.json
```

## What Makes It Different

| Area | What it does now | Why it matters |
| --- | --- | --- |
| `LangChain` providers | Unifies DeepSeek, OpenAI, Anthropic, and OpenAI-compatible endpoints | Swap models without rewriting the scanner |
| `LangGraph` workflow | Models file analysis as `rule_scan -> llm_scan -> merge_and_finalize` | Gives the AI runtime a real pipeline instead of prompt spaghetti |
| `MCP Server` | Exposes structured scan tools for coding agents | Lets Codex and other MCP clients call CodeScan directly |
| `Skill layer` | Ships an installable `codescan-review` skill | Teaches Codex when to scan and how to present findings |
| Report system | Generates HTML / JSON / text output | Works for both humans and automation |
| Tests + CI | Verifies runtime, packaging, docs, and entry points | Keeps the repo from slipping back into prototype quality |

## Architecture

```mermaid
flowchart LR
    A["CLI / GUI"] --> B["CodeScanner"]
    A2["MCP Server"] --> B
    A3["Codex Skill"] --> A2
    B --> C["AIAnalysisService"]
    C --> D["providers.py"]
    C --> E["chains.py"]
    C --> F["workflow.py"]
    B --> G["VulnerabilityDB"]
    B --> H["report.py"]
    F --> I["rule_scan"]
    F --> J["llm_scan"]
    F --> K["merge_and_finalize"]
```

Core layout:

```text
codescan/
├── ai/
│   ├── providers.py
│   ├── prompts.py
│   ├── chains.py
│   ├── workflow.py
│   ├── schemas.py
│   └── service.py
├── scanner.py
├── report.py
├── vulndb.py
├── mcp_server.py
└── __main__.py

skills/
└── codescan-review/
```

## Quick Start

### 1. Clone

```bash
git clone https://github.com/HeJiguang/codescan.git
cd codescan
```

### 2. Install

```bash
python -m venv .venv

# Linux / macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

pip install -e .
```

### 3. Configure a model

```bash
python -m codescan config --show
python -m codescan config --provider deepseek --api-key YOUR_DEEPSEEK_API_KEY --model deepseek-chat
```

### 4. Try the CLI

```bash
python -m codescan file /path/to/file.py
python -m codescan dir /path/to/project
python -m codescan git-merge main
```

### 5. Try the MCP server

```bash
codescan-mcp --transport stdio
```

## Use With Codex

  

To use CodeScan from Codex, combine both layers:

1. Install the `codescan-review` skill
2. Run `codescan-mcp --transport stdio`
3. Ask Codex for a security review with a concrete scan scope

That gives Codex workflow guidance plus real structured scan tools.

Good starter prompts:

```text
Use $codescan-review to inspect the current branch against main and report only actionable security findings.

Use $codescan-review to inspect this file for security issues, especially trust boundaries and command execution risks.

Use $codescan-review to scan this repository and summarize the top security risks by severity.
```

More setup detail is in [Use With Codex](docs/codex.md), [MCP Guide](docs/mcp.md), and [Skill Guide](docs/skill.md).

## Can MCP Actually Improve Agent Security?

Yes, within a review workflow.

CodeScan can improve the safety of agent-authored code when it is used at the right time and treated as a review tool instead of an automatic guarantee:

- highest value: scan the current branch or diff before merge
- strong value: scan a suspicious file that touches auth, SQL, shell execution, file handling, templating, or secrets
- lower value: run a broad repository sweep for intake or triage

What MCP changes is the integration cost. Instead of asking an agent to shell out, wait for reports, and parse result files, CodeScan can return structured findings directly in the review loop.

What MCP does not solve by itself:

- false positives from lightweight rule matching
- missing deeper data-flow or framework-aware analysis
- the need to manually verify high-severity findings before treating them as confirmed

In other words: MCP makes secure review workflows easier for agents to use consistently. It does not turn any scanner into a complete security gate on its own.

## Example Output

  

The repo includes a small intentionally vulnerable fixture plus a representative structured scan result:

- [`examples/demo-vulnerable-app`](examples/demo-vulnerable-app)
- [`examples/sample-mcp-result.json`](examples/sample-mcp-result.json)

These files show the expected result shape before any local model setup.

More detail is in [Example Output](docs/example-output.md).

## Get Involved

Current contribution areas:

- improve rule quality and reduce false positives
- add Semgrep or AST-backed checks
- improve GUI usability or split `gui.py`
- add benchmark repositories and evaluation fixtures
- improve docs, examples, onboarding, and Codex workflows

Start here:

- [Contributing Guide](docs/CONTRIBUTING.md)
- [Good First Issues Guide](docs/good-first-issues.md)
- [Community Guide](docs/community.md)
- [Support](SUPPORT.md)
- [MCP Guide](docs/mcp.md)
- [Skill Guide](docs/skill.md)
- the `good first issues` lane described in the contributing guide

Use the GitHub issue templates for bugs and feature proposals.

## What Ships Today

- Unified provider layer for modern chat models
- LangGraph-based file analysis workflow
- File, directory, GitHub repo, and Git diff scanning
- HTML / JSON / text report generation
- Desktop GUI
- MCP server with structured security tools
- Installable `codescan-review` skill for Codex
- Codex-specific setup guide and workflow visuals
- Demo vulnerable fixture and example MCP-style findings
- GitHub Actions CI and test coverage

## Quality Gate

```bash
python -m pytest tests -q
python -m compileall codescan
python -m codescan --help
python -m codescan mcp --help
```

## Roadmap

- [x] Rebuild the AI runtime with `LangChain + LangGraph`
- [x] Repair CLI / GUI / report-layer contract mismatches
- [x] Add packaging metadata, tests, and public CI
- [x] Publish an MCP server surface for coding agents
- [x] Publish an installable Codex skill
- [x] Add concrete example outputs to the repo homepage
- [ ] Strengthen rule trustworthiness with deeper Semgrep / AST review flows
- [ ] Add SARIF output and GitHub code scanning integration
- [ ] Continue splitting scan/export/settings logic out of `gui.py`
- [ ] Add benchmark repositories and repeatable evaluation fixtures

## Docs

- [Technical Doc](docs/technical_doc.md)
- [MCP Guide](docs/mcp.md)
- [Skill Guide](docs/skill.md)
- [Use With Codex](docs/codex.md)
- [Example Output](docs/example-output.md)
- [Good First Issues](docs/good-first-issues.md)
- [Community Guide](docs/community.md)
- [Contributing](docs/CONTRIBUTING.md)
- [Support](SUPPORT.md)

## License

MIT. See [LICENSE](LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [HeJiguang](https://github.com/HeJiguang)
- **Source:** [HeJiguang/codescan](https://github.com/HeJiguang/codescan)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hejiguang-codescan
- Seller: https://agentstack.voostack.com/s/hejiguang
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.