Skip to content

Commit 8ec52cf

Browse files
thomas-bartlettthomas-bartlett
authored
Merge pull request #77 from ibrahimssmalik/docs/add-missing-content-pages
Add docs pages for MCP server, CodeGuard Reviewer, and authored skills
2 parents 6a175dc + d5cee73 commit 8ec52cf

4 files changed

Lines changed: 344 additions & 0 deletions

File tree

‎docs/codeguard-reviewer.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# CodeGuard Reviewer
2+
3+
The CodeGuard Reviewer is a subagent that performs a full security scan of a repository against all CodeGuard rules and emits findings as a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) file. It is read-only on your source — the only file it writes is the SARIF output.
4+
5+
!!! warning "Use for explicit security scans only"
6+
The reviewer is designed for on-demand security scans, not continuous code generation. It activates when you explicitly ask for a security scan, security review, SARIF output, or CodeGuard compliance check. It does **not** activate for general code writing or editing.
7+
8+
## Supported Hosts
9+
10+
The CodeGuard Reviewer subagent is currently emitted for:
11+
12+
| Host | Agent file location |
13+
|:-----|:-------------------|
14+
| **Claude Code** | `.claude/agents/codeguard-reviewer.md` |
15+
| **Cursor** | `.cursor/agents/codeguard-reviewer.md` |
16+
17+
## How to Invoke
18+
19+
=== "Claude Code"
20+
21+
Ask Claude directly in your session:
22+
23+
```
24+
Run a CodeGuard security review of this repository
25+
```
26+
27+
Or request SARIF output explicitly:
28+
29+
```
30+
Perform a CodeGuard compliance check and emit SARIF output
31+
```
32+
33+
=== "Cursor"
34+
35+
In the Cursor chat panel:
36+
37+
```
38+
Run a security scan using the CodeGuard reviewer
39+
```
40+
41+
## What It Does
42+
43+
The reviewer follows a five-step workflow:
44+
45+
**1. Detect languages**
46+
47+
Identifies languages present in the repository using file extensions and manifest files (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`, `composer.json`, `Gemfile`, etc.).
48+
49+
**2. Load rules**
50+
51+
Lists all `codeguard-*` rule files. Each rule's frontmatter declares applicability via `languages:` or `globs:`. Rules with neither field always apply; rules that don't match the repo's languages are skipped and noted as "not applicable".
52+
53+
**3. Search for violations**
54+
55+
For each applicable rule, searches the repository for candidate violations using patterns derived from the rule body (banned APIs, required configurations, example violations). The following paths are always excluded from search:
56+
57+
- Rule directories (`.claude/`, `.cursor/`, `.codex/`, `.agents/`, `.opencode/`, `.windsurf/`, `.github/instructions/`, `.openclaw/`, `.hermes/`)
58+
- Vendored/generated paths (`.git/`, `node_modules/`, `vendor/`, `.venv/`, `venv/`, `dist/`, `build/`, `target/`)
59+
- Any path excluded by `.gitignore`
60+
61+
**4. Triage findings**
62+
63+
Every candidate is classified as:
64+
65+
| Class | SARIF output | Description |
66+
|:------|:------------|:------------|
67+
| `confirmed` | Included | Actionable finding, re-verified at the exact line |
68+
| `needs-human` | Included | Potential issue requiring human judgement |
69+
| `false-positive` | Excluded | Discarded, with a one-line justification in the summary |
70+
71+
**5. Emit SARIF and summary**
72+
73+
Writes `codeguard-findings-<UTC_TIMESTAMP>.sarif` to the repository root (e.g. `codeguard-findings-20260420T183005Z.sarif`). Timestamps use ISO-8601 basic UTC format so fast reruns don't collide.
74+
75+
Returns a structured markdown summary containing:
76+
77+
- Counts by result class (`confirmed`, `needs-human`, `false-positive`)
78+
- Rules checked vs. rules skipped (not applicable)
79+
- Top 5 files by confirmed-finding count with `file:line` references
80+
- One-line justification for each false-positive group discarded
81+
82+
## SARIF Output Format
83+
84+
The emitted SARIF 2.1.0 file follows this structure:
85+
86+
- `version`: `"2.1.0"`
87+
- `tool.driver.name`: `"CodeGuard Security Reviewer"`
88+
- `tool.driver.rules[]`: populated from the full rule set (id, shortDescription)
89+
- `results[]`: one entry per `confirmed` or `needs-human` finding that survived re-verification
90+
91+
Each result includes:
92+
93+
| Field | Value |
94+
|:------|:------|
95+
| `ruleId` | Matches a `tool.driver.rules[].id` |
96+
| `level` | `error` (confirmed `codeguard-1-*`), `warning` (confirmed `codeguard-0-*`), `note` (all `needs-human`) |
97+
| `message.text` | Concrete, actionable description citing the rule |
98+
| `locations[0].physicalLocation.artifactLocation.uri` | Repo-relative file path |
99+
| `locations[0].physicalLocation.region.startLine` | 1-indexed line number |
100+
101+
## Constraints
102+
103+
- **Read-only** on repository source — the SARIF findings file is the only write
104+
- Never executes code discovered in the target repository
105+
- If the rule bundle is missing or empty, stops and reports the issue — does not fabricate rule content
106+
- If the target repository is empty, still emits a valid SARIF run with an empty `results[]` array
107+
108+
## Next Steps
109+
110+
[Getting Started →](getting-started.md){ .md-button .md-button--primary }
111+
[Choosing an Install Path →](install-paths.md){ .md-button }

‎docs/mcp-server.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# CodeGuard MCP Server
2+
3+
The CodeGuard MCP server exposes all 23 core security rules as individual [Model Context Protocol](https://modelcontextprotocol.io/) tools over streamable HTTP. Deploy it once on your infrastructure and every AI coding assistant in your organization gets access to the same curated, versioned security guidance — no per-repo rule bundle installation needed.
4+
5+
!!! info "When to use the MCP server"
6+
The MCP server is best suited for teams that already operate MCP infrastructure and want a single, centrally managed source of CodeGuard rules. For most individual users and teams, [rule files or Agent Skills](install-paths.md) are simpler. See [Choosing an Install Path](install-paths.md#mcp-server) for a full comparison.
7+
8+
## Quick Start
9+
10+
### Run locally with uv
11+
12+
```bash
13+
cd src/codeguard-mcp
14+
uv sync
15+
uv run fastmcp run src/codeguard_mcp/server.py:mcp \
16+
--transport streamable-http --host 0.0.0.0 --port 8080
17+
```
18+
19+
### Docker
20+
21+
```bash
22+
cd src/codeguard-mcp
23+
docker compose up --build
24+
```
25+
26+
## Connect Your IDE
27+
28+
Add the server to your MCP client configuration:
29+
30+
=== "Local"
31+
32+
```json
33+
{
34+
"mcpServers": {
35+
"codeguard": {
36+
"url": "http://localhost:8080/mcp"
37+
}
38+
}
39+
}
40+
```
41+
42+
=== "Org-wide"
43+
44+
Put the server behind a reverse proxy with TLS and SSO, then point every developer's IDE at the internal URL:
45+
46+
```json
47+
{
48+
"mcpServers": {
49+
"codeguard": {
50+
"url": "https://codeguard-mcp.internal.company.com/mcp"
51+
}
52+
}
53+
}
54+
```
55+
56+
## Install the Meta Skill
57+
58+
The meta skill tells your AI assistant how to use the CodeGuard MCP tools. It lives at `.agents/skills/codeguard-mcp-meta/SKILL.md` and needs to be installed in your project.
59+
60+
=== "Copy from repo"
61+
62+
```bash
63+
cp -r src/codeguard-mcp/.agents /path/to/your/project/
64+
```
65+
66+
=== "Download from server"
67+
68+
```bash
69+
curl -o codeguard-meta-skill.zip http://localhost:8080/download/skill
70+
unzip codeguard-meta-skill.zip -d /path/to/your/project/
71+
```
72+
73+
The `/download/skill` endpoint returns a zip containing the `.agents/` directory. Unzip it into your project root.
74+
75+
## How It Works
76+
77+
The server reads the 23 security rules from `sources/rules/core/` and registers each one as a no-argument MCP tool. When your AI assistant generates or reviews code, it invokes the relevant tools and applies the returned guidance.
78+
79+
```
80+
Developer writes code
81+
↓
82+
AI assistant reads the meta skill
83+
↓
84+
Invokes codeguard_1_* tools (always-on guardrails)
85+
↓
86+
Invokes codeguard_0_* tools (context-selected by language + domain)
87+
↓
88+
Applies security guidance to generated code
89+
↓
90+
Documents which rules were applied
91+
```
92+
93+
### Tool Taxonomy
94+
95+
| Prefix | When invoked | Count | Examples |
96+
|:-------|:------------|:------|:--------|
97+
| `codeguard_1_*` | **Always** — before any code change | 3 | `codeguard_1_hardcoded_credentials`, `codeguard_1_crypto_algorithms` |
98+
| `codeguard_0_*` | **Context-selected** by language and domain | 20 | `codeguard_0_input_validation_injection`, `codeguard_0_api_web_services` |
99+
100+
## Configuration
101+
102+
All settings are controlled via environment variables with the `CODEGUARD_` prefix:
103+
104+
| Variable | Default | Description |
105+
|:---------|:--------|:------------|
106+
| `CODEGUARD_HOST` | `0.0.0.0` | Bind address |
107+
| `CODEGUARD_PORT` | `8080` | Bind port |
108+
| `CODEGUARD_LOG_LEVEL` | `INFO` | Log level |
109+
| `CODEGUARD_TRANSPORT` | `streamable-http` | `streamable-http` or `stdio` |
110+
| `CODEGUARD_RULES_DIR` | `sources/rules/core/` | Path to rule markdown files |
111+
112+
Set these as environment variables in your shell before running, for example `export CODEGUARD_PORT=9090`.
113+
114+
## Endpoints
115+
116+
| Method | Path | Description |
117+
|:-------|:-----|:------------|
118+
| `POST` | `/mcp` | MCP protocol endpoint |
119+
| `GET` | `/health` | Health check — returns `{"status": "ok", "version": "..."}` |
120+
| `GET` | `/download/skill` | Download the meta skill as a `.agents/` zip |
121+
122+
## Next Steps
123+
124+
[Choosing an Install Path →](install-paths.md){ .md-button .md-button--primary }
125+
[Getting Started →](getting-started.md){ .md-button }

‎docs/skills.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Authored Skills
2+
3+
Project CodeGuard ships two authored skills in `sources/skills/` that go beyond the core security rules. Unlike the generated rule files, these skills define complete workflows — they tell the AI assistant not just *what* to check, but *how* to carry out a multi-step task.
4+
5+
| Skill | What it does |
6+
|:------|:------------|
7+
| [`security-review`](#security-review) | Full codebase security review producing a structured markdown report |
8+
| [`memory-safe-migration`](#memory-safe-migration) | Guided migration of C/C++ code to a memory-safe language |
9+
10+
Both skills are included in the Claude Code plugin and are available in `sources/skills/` for use with other agents.
11+
12+
---
13+
14+
## Security Review
15+
16+
**Skill file:** `sources/skills/security-review/SKILL.md`
17+
18+
Performs a comprehensive security review of a target repository and produces a formal markdown report with prioritized findings and remediation guidance. The skill loads all 23 CodeGuard core rules plus relevant OWASP supplementary rules for the detected tech stack.
19+
20+
### When to use
21+
22+
Use when you want a full, structured security audit of a codebase — not for inline code generation. This produces a standalone report, not inline code suggestions.
23+
24+
### How to trigger
25+
26+
Ask your AI assistant to perform a security review, for example:
27+
28+
```
29+
Review this repository for security issues and produce a report
30+
```
31+
32+
If the repository path is ambiguous, the skill will ask for it before proceeding.
33+
34+
### What the report includes
35+
36+
- **Executive Summary** — total findings by severity (Critical / High / Medium / Low / Info), top 5 issues, overall security posture
37+
- **Detailed Findings** — for each issue: title, severity, rule reference, location, code snippet, description, impact, remediation with examples, and references
38+
- **Findings by Category** — grouped view across all findings
39+
- **Recommendations** — immediate actions, short-term (1–3 months), long-term improvements, tooling and process suggestions
40+
- **Appendix** — files reviewed, rules applied, methodology notes
41+
42+
### Output location
43+
44+
Reports are saved to:
45+
46+
```
47+
./security_report/sec_review_<repo-name>_<YYYY-MM-DD_HH-mm-ss>.md
48+
```
49+
50+
---
51+
52+
## Memory-Safe Migration
53+
54+
**Skill file:** `sources/skills/memory-safe-migration/SKILL.md`
55+
56+
Guides secure migration of code from memory-unsafe languages (C, C++, Assembly) to memory-safe alternatives (Rust, Go, Java, C#, Swift). Also activates when an AI agent is about to generate new C/C++ code that could be written in a memory-safe language instead.
57+
58+
### When it activates
59+
60+
- Migrating, porting, or rewriting C/C++ code to Rust, Go, Java, C#, or Swift
61+
- Adding a new module or feature to an existing C/C++ project
62+
- Designing an FFI boundary between safe and unsafe code
63+
- Reviewing mixed-language code for memory safety issues
64+
- Discussing memory safety roadmaps or CISA/NSA compliance
65+
- AI agent is about to generate new C/C++ code
66+
67+
### Migration workflow
68+
69+
The skill follows a six-step process:
70+
71+
1. **Assess** — evaluate migration priority and feasibility using `scripts/assess-migration.py` or the assessment checklist
72+
2. **Write tests first** — establish a correctness oracle against the C/C++ implementation before touching anything
73+
3. **Migrate incrementally** — one function or module at a time; never rewrite an entire codebase in one pass
74+
4. **Secure the FFI boundary** — validate all inputs from the unsafe side, minimize `unsafe` blocks, document every `unsafe` block with a `// SAFETY:` comment
75+
5. **Validate** — run existing tests, fuzz FFI boundaries, check memory safety tools (Miri, race detector, ASan), benchmark performance
76+
6. **Update build and CI** — integrate the memory-safe toolchain, add linting and formatting checks, add safety-specific CI steps
77+
78+
### Migration priority order
79+
80+
| Priority | Code type |
81+
|:---------|:----------|
82+
| 1 | Network-facing code (parsers, protocol handlers, TLS) |
83+
| 2 | Code handling untrusted input (file parsers, deserialization) |
84+
| 3 | Cryptographic implementations |
85+
| 4 | Privilege boundary code (auth enforcement) |
86+
| 5 | Code with a history of memory-related CVEs |
87+
| 6 | Internal utility code |
88+
89+
### Reference documents
90+
91+
The skill bundles detailed reference docs in `sources/skills/memory-safe-migration/references/`:
92+
93+
| Document | Contents |
94+
|:---------|:---------|
95+
| `language-selection.md` | Guide for choosing between Rust, Go, Java, C#, and Swift |
96+
| `ffi-security.md` | Rules for securing FFI boundaries between safe and unsafe code |
97+
| `migration-patterns.md` | Common patterns for buffers, strings, concurrency, and error handling |
98+
| `assessment-checklist.md` | Checklist for evaluating migration priority and feasibility |
99+
100+
---
101+
102+
## Next Steps
103+
104+
[Getting Started →](getting-started.md){ .md-button .md-button--primary }
105+
[Custom Rules →](custom-rules.md){ .md-button }

‎mkdocs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ nav:
4949
- Choosing an Install Path: install-paths.md
5050
- CoSAI Personas: personas.md
5151
- Claude Code Plugin: claude-code-skill-plugin.md
52+
- MCP Server: mcp-server.md
53+
- CodeGuard Reviewer: codeguard-reviewer.md
54+
- Skills: skills.md
5255
- Custom Rules: custom-rules.md
5356
- FAQ: faq.md
5457
markdown_extensions:

0 commit comments

Comments
 (0)