Skip to content

Getting Started

Get up and running with Project CodeGuard in just a few steps.

Project CodeGuard Introduction Video

This video introduces Project CodeGuard and includes several demos on how to use it during code generation and code review with Claude Code, Codex, and other coding agents.

Prerequisites

Before you begin, familiarize yourself with how rules work in your AI coding tool:

Cursor uses .cursor/rules for rule configuration.

Cursor Rules Documentation

Windsurf uses .windsurf/rules for rule configuration.

Windsurf Rules Documentation

GitHub Copilot uses .github/instructions for rule configuration.

GitHub Copilot Instructions

Antigravity uses .agent/rules for rule configuration.

Antigravity Instructions

OpenCode uses .opencode/skills for skill configuration.

OpenCode Skills Documentation

Installation

Select your AI coding tool and follow the instructions:

  1. Download ide-rules-cursor.zip from the Releases page
  2. Extract the ZIP file

  3. Copy the .cursor/ directory to your project root:

    cp -r .cursor/ /path/to/your/project/

  4. Restart Cursor to load the rules

  1. Download ide-rules-windsurf.zip from the Releases page
  2. Extract the ZIP file

  3. Copy the .windsurf/ directory to your project root:

    cp -r .windsurf/ /path/to/your/project/

  4. Restart Windsurf to load the rules

  1. Download ide-rules-copilot.zip from the Releases page
  2. Extract the ZIP file

  3. Copy the .github/ directory to your project root:

    cp -r .github/ /path/to/your/project/

  4. Restart your IDE to load the instructions

  1. Download ide-rules-antigravity.zip from the Releases page
  2. Extract the ZIP file

  3. Copy the .agent/ directory to your project root:

    cp -r .agent/ /path/to/your/project/

  4. Restart Antigravity to load the rules

Option A: Skills (recommended)

Using skills is more context-efficient as only relevant rules are loaded per session based on the files you're working with.

  1. Download ide-rules-opencode.zip from the Releases page
  2. Extract the ZIP file

  3. Copy the .opencode/ directory to your project root:

    cp -r .opencode/ /path/to/your/project/

  4. Restart OpenCode to load the skill

Option B: Remote Instructions (zero-maintenance)

All rules loaded every session, but always up to date: no local files to maintain.

Create an opencode.json in your project root:

opencode.json with remote URLs 
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-additional-cryptography.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-api-web-services.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-authentication-mfa.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-authorization-access-control.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-client-side-web-security.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-cloud-orchestration-kubernetes.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-data-storage.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-devops-ci-cd-containers.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-file-handling-and-uploads.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-framework-and-languages.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-iac-security.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-input-validation-injection.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-logging.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-mcp-security.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-mobile-apps.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-privacy-data-protection.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-safe-c-functions.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-session-management-and-cookies.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-supply-chain-security.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-0-xml-and-serialization.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-1-crypto-algorithms.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-1-digital-certificates.md",
    "https://raw.githubusercontent.com/cosai-oasis/project-codeguard/main/sources/core/codeguard-1-hardcoded-credentials.md"
  ]
}

Tradeoff

The skills approach (Option A) uses glob-scoped rules so only relevant rules are loaded based on the files you're editing. Remote instructions load all 23 rules into every session regardless of language. Remote URLs point to the main branch -- pin to a release tag (e.g. refs/tags/v1.3.0) if you need a stable, auditable snapshot.

Claude Code uses a plugin system instead of manual file installation:

  1. Add the Project CodeGuard marketplace:

    /plugin marketplace add cosai-oasis/project-codeguard

  2. Install the security plugin:

    /plugin install codeguard-security@project-codeguard

The plugin automatically loads and applies security rules. See the Claude Code Plugin documentation for details.

OpenAI Codex uses agent skills for task-specific instructions.

Prerequisites

Make sure you're running the latest version of Codex before installing skills.

Option A: Skill installer

$skill-installer install from https://github.com/cosai-oasis/project-codeguard/tree/main/skills/software-security

Option B: Manual clone

mkdir -p .codex/skills
cd .codex/skills
git clone https://github.com/cosai-oasis/project-codeguard.git temp
mv temp/skills/software-security ./
rm -rf temp

Once installed, invoke the skill with $software-security or let Codex use it automatically when writing or reviewing code.

Codex Skills Documentation

For more information, see the OpenAI Codex Skills documentation.

Using multiple tools? Download ide-rules-all.zip for all formats in one archive.

Repository Level Installation

Installing at the repository level ensures all team members benefit from the security rules automatically when they clone the repository.

Hidden Files on macOS/Linux

On macOS/Linux, you may need to show hidden files:

  • macOS Finder: Press Cmd+Shift+. to toggle visibility
  • Linux: Use ls -la in terminal or enable "Show Hidden Files" in your file manager

Option 2: Build from Source

If you want to customize or contribute to the rules:

# Clone the repository
git clone https://github.com/cosai-oasis/project-codeguard.git
cd rules

# Install dependencies (requires Python 3.11+)
uv sync

# Validate rules
uv run python src/validate_unified_rules.py sources/

# Convert rules (default: core rules only)
uv run python src/convert_to_ide_formats.py

# Or include all rules (core + owasp supplementary)
uv run python src/convert_to_ide_formats.py --source core owasp

# Copy the generated rules to your project
cp -r dist/.cursor/ /path/to/your/project/
cp -r dist/.windsurf/ /path/to/your/project/
cp -r dist/.github/ /path/to/your/project/
cp -r dist/.agent/ /path/to/your/project/
cp -r dist/.opencode/ /path/to/your/project/

Core vs OWASP Sources

Project CodeGuard has two source rule sets:

  • sources/core/: Official Project CodeGuard rules. These are the main rules packaged in releases and enabled by default.
  • sources/owasp/: Supplementary rules originally derived from OWASP guidance. These are optional and are not enabled by default.

Use OWASP supplementary rules when you explicitly want broader coverage, such as deeper security reviews or reference-driven review workflows.

Rule Types: Always-On vs Glob-Scoped

Project CodeGuard supports two rule activation types:

  • Always-on rules: Apply to all files in the project. These rules are for baseline safeguards that should always be in context.
  • Glob-scoped rules: Apply only to matching file patterns (derived from languages in source frontmatter). These rules are for language- or framework-specific guidance.

Keeping Rules Updated (Automated)

For GitHub repositories, you can automate rule updates with a workflow that runs monthly and creates PRs when new versions are available.

Supported Formats

  • Cursor (.cursor/rules/)
  • Windsurf (.windsurf/rules/)
  • GitHub Copilot (.github/instructions/)
  • Antigravity (.agent/rules/)
  • OpenCode (.opencode/skills/software-security/rules/)

Setup

  1. Download update-codeguard-rules.yml
  2. Save to .github/workflows/update-codeguard-rules.yml in your repository
  3. Commit and push

The workflow runs monthly (1st at 9:00 UTC) and can also be triggered manually from the Actions tab.

Verify Installation

After installation, your project structure should include:

your-project/
├── .agent/
│   └── rules/
├── .cursor/
│   └── rules/
├── .github/
│   └── instructions/
├── .opencode/
│   └── skills/
│       └── software-security/
├── .windsurf/
│   └── rules/
└── ... (your project files)

What's Included

The security rules cover essential areas:

Core Security Rules

  • 🔐 Cryptography: Safe algorithms, secure key management, TLS configuration
  • 🛡️ Input Validation: SQL injection, XSS prevention, command injection defense
  • 🔑 Authentication: MFA, OAuth/OIDC, password security, session management
  • ⚡ Authorization: RBAC/ABAC, access control, privilege escalation prevention

Platform-Specific Rules

  • 📱 Mobile Apps: iOS/Android security, secure storage, transport security
  • 🌐 API Security: REST/GraphQL/SOAP security, rate limiting, SSRF prevention
  • ☁️ Cloud & Containers: Docker/Kubernetes hardening, IaC security
  • 🗄️ Data Storage: Database security, encryption, backup protection

DevOps & Supply Chain

  • 📦 Dependencies: Supply chain security, SBOM, vulnerability management
  • 🔄 CI/CD: Pipeline security, artifact signing, secrets management
  • 📝 Logging: Secure logging, monitoring, privacy-aware telemetry

Testing the Integration

To verify the rules are working:

  1. Open your IDE with the Project CodeGuard rules installed
  2. Start a new file in a supported language (Python, JavaScript, Java, C/C++, etc.)
  3. Ask your AI assistant to generate code that might have security implications:
  4. "Create a function to hash a password"
  5. "Write code to connect to a database"

  6. "Generate an API endpoint with authentication"

  7. Observe the output - The AI should automatically apply security best practices:

  8. Using strong cryptographic algorithms (bcrypt/Argon2 for passwords)
  9. Parameterized queries to prevent SQL injection
  10. Proper authentication/authorization checks

Next Steps

  • Review Rules: Explore the security rules in your IDE's rules directory
  • Test Integration: Generate some code and see the security guidance in action
  • Share Feedback: Help us improve by opening an issue
  • Contribute: See CONTRIBUTING.md to contribute new rules or improvements

You're Ready!

Project CodeGuard is now protecting your development workflow. The security rules will automatically guide AI assistants to generate more secure code.

Troubleshooting

Rules Not Working

If the AI assistant doesn't seem to follow the rules:

  1. Restart your IDE to ensure rules are loaded
  2. Check file location - Ensure rules are in the correct directory for your IDE
  3. Verify file format - Rules should be markdown files
  4. Test with explicit request - Ask the AI directly: "Follow the security rules when generating this code"

Performance Impact

The rules have minimal performance impact, but if you experience issues:

  • Reduce rule count: Start with core rules (cryptography, input validation, authentication)
  • Combine rules: Merge related rules into fewer files
  • Report issues: Let us know via GitHub Issues

Getting Help