Merge pull request #90 from project-codeguard/develop

Updated codeguard-1-crypto-algorithms.md rule to include guidance on post quantum cryptography
Updated ClaudeCodeSkills to a more generic class AgentSkills after Agent Skills are adopted as a standard.
Fixed codeguard-1-digital-certificates.md so that the agent does not assume certificate parsing capabilities.
Updated codeguard-0-input-validation-injection.md to include guidance on SOQL along with SQL.
Added documentation for generating custom rule files.

Author: ramraaj25

README.md

@@ -54,7 +54,7 @@ Get started in minutes:
 ## How It Works
 
 1. **Security rules** are written in unified markdown format (`sources/` directory)
-2. **Conversion tools** translate rules to IDE-specific formats (Cursor, Windsurf, Copilot, Claude Code, Antigravity)
+2. **Conversion tools** translate rules to IDE-specific formats (Cursor, Windsurf, Copilot, Agent Skills, Antigravity)
 3. **Release automation** packages rules into downloadable ZIP files
 4. **AI assistants** reference these rules when generating or reviewing code
 5. **Secure code** is produced automatically without developer intervention
@@ -63,7 +63,7 @@ Get started in minutes:
 
 ```
 sources/           # Source rules
-skills/            # Claude Code plugin (generated, committed)
+skills/            # Agent Skills format (generated, committed)
 src/               # Conversion and validation tools
 dist/              # Other IDE bundles (generated, not committed)
 ```
@@ -78,6 +78,7 @@ python src/convert_to_ide_formats.py  # Generate skills/ and dist/
 ```
 
 **More options**: `python src/convert_to_ide_formats.py --help`  
+**Custom rules**: Create your own rules — see [Custom Rules](https://project-codeguard.org/custom-rules/)  
 **Maintainers**: See [CONTRIBUTING.md](CONTRIBUTING.md) for release process.
 
 ## Community

docs/custom-rules.md

@@ -0,0 +1,79 @@
+# Custom Rules
+
+Create custom rules to enforce your own policies, compliance requirements, or coding standards.
+
+## Quick Start
+
+1. **Create a source folder** under `sources/`:
+   ```
+   sources/
+   ├── core/           # Project CodeGuard rules
+   ├── owasp/          # OWASP supplementary rules
+   └── my-rules/       # Your custom rules
+   ```
+
+2. **Copy the template** from `sources/templates/custom-rule-template.md.example` and customize it
+
+3. **Build with your rules**:
+   ```bash
+   uv run python src/convert_to_ide_formats.py --source core my-rules
+   ```
+
+## Frontmatter Schema
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | Yes | Brief description of the rule |
+| `languages` | If `alwaysApply` is false | List of languages this rule applies to |
+| `alwaysApply` | No | If `true`, rule applies to all files (omit `languages`) |
+| `tags` | No | Categories for filtering: `authentication`, `data-security`, `infrastructure`, `privacy`, `secrets`, `web` |
+
+## CLI Reference
+
+### convert_to_ide_formats.py
+
+Converts source rules to IDE-specific formats.
+
+| Option | Description |
+|--------|-------------|
+| `--source` | Source folders under `sources/` to include. Default: `core` |
+| `--output-dir`, `-o` | Output directory for generated bundles. Default: `dist` |
+| `--tag` | Filter rules by tags (comma-separated, case-insensitive, AND logic) |
+
+**Examples:**
+
+```bash
+# Default: convert core rules only
+uv run python src/convert_to_ide_formats.py
+
+# Include multiple sources
+uv run python src/convert_to_ide_formats.py --source core owasp my-rules
+
+# Custom output directory
+uv run python src/convert_to_ide_formats.py --source core my-rules -o build
+
+# Filter to only rules tagged with data-security
+uv run python src/convert_to_ide_formats.py --tag data-security
+
+# Multiple tags (AND logic - rules must have ALL tags)
+uv run python src/convert_to_ide_formats.py --tag data-security,authentication
+```
+
+### validate_unified_rules.py
+
+Validates rule files have correct frontmatter and structure before building.
+
+```bash
+# Validate all rules in a directory
+uv run python src/validate_unified_rules.py sources/my-rules/
+
+# Validate all sources
+uv run python src/validate_unified_rules.py sources/
+```
+
+## Notes
+
+- Filenames must be unique across all sources
+- Use `.md` extension for all rule files
+- Rules are converted to all supported IDE formats
+- To add new tags, update `KNOWN_TAGS` in `src/tag_mappings.py`

skills/software-security/SKILL.md

@@ -29,6 +29,7 @@ When writing or reviewing code:
 
 | Language | Rule Files to Apply |
 |----------|---------------------|
+| apex | codeguard-0-input-validation-injection.md |
 | c | codeguard-0-additional-cryptography.md, codeguard-0-api-web-services.md, codeguard-0-authentication-mfa.md, codeguard-0-authorization-access-control.md, codeguard-0-client-side-web-security.md, codeguard-0-data-storage.md, codeguard-0-file-handling-and-uploads.md, codeguard-0-framework-and-languages.md, codeguard-0-iac-security.md, codeguard-0-input-validation-injection.md, codeguard-0-logging.md, codeguard-0-safe-c-functions.md, codeguard-0-session-management-and-cookies.md, codeguard-0-xml-and-serialization.md |
 | cpp | codeguard-0-safe-c-functions.md |
 | d | codeguard-0-iac-security.md |

skills/software-security/rules/codeguard-0-input-validation-injection.md

@@ -1,6 +1,7 @@
 ---
-description: Input validation and injection defense (SQL/LDAP/OS), parameterization, prototype pollution
+description: Input validation and injection defense (SQL/SOQL/LDAP/OS), parameterization, prototype pollution
 languages:
+- apex
 - c
 - go
 - html
@@ -49,6 +50,16 @@ pstmt.setString( 1, custname);
 ResultSet results = pstmt.executeQuery( );
 ```
 
+### SOQL/SOSL Injection (Salesforce)
+
+SOQL and SOSL are query/search languages (no SQL-style DDL/DML). Data changes are performed via Apex DML or Database methods. Note: SOQL can lock rows via `FOR UPDATE`.
+
+- Primary risk: data exfiltration by bypassing intended query filters/business logic; impact is amplified when Apex runs with elevated access (system mode) or when CRUD/FLS aren't enforced.
+- Second-order risk (conditional): if queried records are passed to DML, injection can broaden the record set and cause unintended mass updates/deletes.
+- Prefer static SOQL/SOSL with bind variables: `[SELECT Id FROM Account WHERE Name = :userInput]` or `FIND :term`.
+- For dynamic SOQL, use `Database.queryWithBinds()`; for dynamic SOSL, use `Search.query()`. Allow‑list any dynamic identifiers. If concatenation is unavoidable, escape string values with `String.escapeSingleQuotes()`.
+- Enforce CRUD/FLS with `WITH USER_MODE` or `WITH SECURITY_ENFORCED` (don't combine both). Enforce record sharing with `with sharing` or user-mode operations. Use `Security.stripInaccessible()` before DML.
+
 ### LDAP Injection Prevention
 - Always apply context‑appropriate escaping:
   - DN escaping for `\ # + < > , ; " =` and leading/trailing spaces

skills/software-security/rules/codeguard-1-crypto-algorithms.md

@@ -1,115 +1,126 @@
 ---
-description: Cryptographic Security Guidelines
+description: Cryptographic Security Guidelines & Post-Quantum Readiness
 alwaysApply: true
 ---
 
 rule_id: codeguard-1-crypto-algorithms
 
-# Cryptographic Security Guidelines
+# Cryptographic Security Guidelines & Post-Quantum Readiness
 
-## Banned (Insecure) Algorithms
+## 1. Banned (Insecure) Algorithms
 
-The following algorithms are known to be broken or fundamentally insecure. **NEVER** generate or use code with these algorithms.
-Examples:
+The following algorithms are known to be broken or fundamentally insecure. NEVER generate or use code with these algorithms.
 
-* Hash: `MD2`, `MD4`, `MD5`, `SHA-0`
-* Symmetric: `RC2`, `RC4`, `Blowfish`, `DES`, `3DES`
-* Key Exchange: Static RSA, Anonymous Diffie-Hellman
-* Classical: `Vigenère`
+*   Hash: `MD2`, `MD4`, `MD5`, `SHA-0`
+*   Symmetric: `RC2`, `RC4`, `Blowfish`, `DES`, `3DES`
+*   Key Exchange: Static RSA, Anonymous Diffie-Hellman
+*   Classical: `Vigenère`
 
-## Deprecated (Legacy/Weak) Algorithms
+Reason: These are cryptographically broken and vulnerable to collision or man-in-the-middle attacks.
 
-The following algorithms are not outright broken, but have known weaknesses, or are considered obsolete. **NEVER** generate or use code with these algorithms.
-Examples:
+## 2. Deprecated (Legacy/Weak) Algorithms
 
-* Hash: `SHA-1`
-* Symmetric: `AES-CBC`, `AES-ECB`
-* Signature: RSA with `PKCS#1 v1.5` padding
-* Key Exchange: DHE with weak/common primes
+The following algorithms have known weaknesses or are considered obsolete. Avoid in new designs and prioritize migration.
 
+*   Hash: `SHA-1`
+*   Symmetric: `AES-CBC`, `AES-ECB`
+*   Signature: RSA with `PKCS#1 v1.5` padding
+*   Key Exchange: DHE with weak/common primes
 
-## Deprecated SSL/Crypto APIs - FORBIDDEN
-NEVER use these deprecated functions. Use the replacement APIs listed below:
+## 3. Recommended & Post-Quantum Ready Algorithms
 
-### Symmetric Encryption (AES)
+Implement these modern, secure algorithms to ensure resistance against both classical and quantum threats.
+
+### Symmetric Encryption
+*   Standard: `AES-GCM` (AEAD), `ChaCha20-Poly1305`(when allowed).
+*   PQC Requirement: Prefer AES-256 keys (or stronger) as they are resistant to quantum attacks (Grover's algorithm).
+*   Avoid: Custom crypto or unauthenticated modes.
+
+### Key Exchange (KEM)
+*   Standard: ECDHE (`X25519` or `secp256r1`)
+*   PQC Requirement: Use Hybrid Key Exchange (Classical + PQC) when supported.
+    *   Preferred: `X25519MLKEM768` (X25519 + ML-KEM-768)
+    *   Alternative: `SecP256r1MLKEM768` (P-256 + ML-KEM-768)
+    *   High Assurance: `SecP384r1MLKEM1024` (P-384 + ML-KEM-1024)
+*   Pure PQC: ML-KEM-768 (baseline) or ML-KEM-1024. Avoid ML-KEM-512 unless explicitly risk-accepted.
+*   Constraints:
+    *   Use vendor-documented identifiers (RFC 9242/9370).
+    *   Remove legacy/draft "Hybrid-Kyber" groups (e.g., `X25519Kyber`) and draft or hardcoded OIDs.
+
+### Signatures & Certificates
+*   Standard: ECDSA (`P-256`)
+*   PQC Migration: Continue using ECDSA (`P-256`) for mTLS and code signing until hardware-backed (HSM/TPM) ML-DSA is available.
+*   Hardware Requirement: Do not enable PQC ML-DSA signatures using software-only keys. Require HSM/TPM storage.
+
+### Protocol Versions
+*   (D)TLS: Enforce (D)TLS 1.3 only (or later).
+*   IPsec: Enforce IKEv2 only.
+    *   Use ESP with AEAD (AES-256-GCM).
+    *   Require PFS via ECDHE.
+    *   Implement RFC 9242 and RFC 9370 for Hybrid PQC (ML-KEM + ECDHE).
+    *   Ensure re-keys (CREATE_CHILD_SA) maintain hybrid algorithms.
+*   SSH: Enable only vendor-supported PQC/hybrid KEX (e.g., `sntrup761x25519`).
+
+## 4. Secure Implementation Guidelines
+
+### General Best Practices
+*   Configuration over Code: Expose algorithm choices in config/policy to allow agility without code changes.
+*   Key Management:
+    *   Use KMS/HSM for key storage.
+    *   Generate keys with a CSPRNG.
+    *   Separate encryption keys from signature keys.
+    *   Rotate keys per policy.
+    *   NEVER hardcode keys, secrets, or experimental OIDs.
+*   Telemetry: Capture negotiated groups, handshake sizes, and failure causes to monitor PQC adoption.
+
+### Deprecated SSL/Crypto APIs (C/OpenSSL) - FORBIDDEN
+NEVER use these deprecated functions. Use the replacement EVP high-level APIs.
+
+#### Symmetric Encryption (AES)
 - Deprecated: `AES_encrypt()`, `AES_decrypt()`
-- Replacement: Use EVP high-level APIs:
-  ```c
-  EVP_EncryptInit_ex()
+- Replacement:
+
+  EVP_EncryptInit_ex()   // Use EVP_aes_256_gcm() for PQC readiness
   EVP_EncryptUpdate()
   EVP_EncryptFinal_ex()
-  EVP_DecryptInit_ex()
-  EVP_DecryptUpdate()
-  EVP_DecryptFinal_ex()
-  ```
-
-### RSA Operations
-- Deprecated: `RSA_new()`, `RSA_up_ref()`, `RSA_free()`, `RSA_set0_crt_params()`, `RSA_get0_n()`
-- Replacement: Use EVP key management APIs:
-  ```c
+
+
+#### RSA/PKEY Operations
+- Deprecated: `RSA_new()`, `RSA_free()`, `RSA_get0_n()`
+- Replacement:
+
   EVP_PKEY_new()
   EVP_PKEY_up_ref()
   EVP_PKEY_free()
-  ```
-
-### Hash Functions
-- Deprecated: `SHA1_Init()`, `SHA1_Update()`, `SHA1_Final()`
-- Replacement: Use EVP digest APIs:
-  ```c
-  EVP_DigestInit_ex()
-  EVP_DigestUpdate()
-  EVP_DigestFinal_ex()
-  EVP_Q_digest()  // For simple one-shot hashing
-  ```
-
-### MAC Operations
-- Deprecated: `CMAC_Init()`, `HMAC()` (especially with SHA1)
-- Replacement: Use EVP MAC APIs:
-  ```c
-  EVP_Q_MAC()  // For simple MAC operations
-  ```
-
-### Key Wrapping
-- Deprecated: `AES_wrap_key()`, `AES_unwrap_key()`
-- Replacement: Use EVP key wrapping APIs or implement using EVP encryption
-
-### Other Deprecated Functions
-- Deprecated: `DSA_sign()`, `DH_check()`
-- Replacement: Use corresponding EVP APIs for DSA and DH operations
-
-## Banned Insecure Algorithms - STRICTLY FORBIDDEN
-These algorithms MUST NOT be used in any form:
-
-### Hash Algorithms (Banned)
-- MD2, MD4, MD5, SHA-0
-- Reason: Cryptographically broken, vulnerable to collision attacks
-- Use Instead: SHA-256, SHA-384, SHA-512
-
-### Symmetric Ciphers (Banned)
-- RC2, RC4, Blowfish, DES, 3DES
-- Reason: Weak key sizes, known vulnerabilities
-- Use Instead: AES-128, AES-256, ChaCha20
-
-### Key Exchange (Banned)
-- Static RSA key exchange
-- Anonymous Diffie-Hellman
-- Reason: No forward secrecy, vulnerable to man-in-the-middle attacks
-- Use Instead: ECDHE, DHE with proper validation
-
-## Broccoli Project Specific Requirements
-- HMAC() with SHA1: Deprecated per Broccoli project requirements
+ 
+
+#### Hash & MAC Functions
+- Deprecated: `SHA1_Init()`, `HMAC()` (especially with SHA1)
+- Replacement:
+
+  EVP_DigestInit_ex() // Use SHA-256 or stronger
+  EVP_Q_MAC()         // For one-shot MAC
+
+
+## 5. Broccoli Project Specific Requirements
+- HMAC() with SHA1: Deprecated.
 - Replacement: Use HMAC with SHA-256 or stronger:
-  ```c
-  // Instead of HMAC() with SHA1
-  EVP_Q_MAC(NULL, "HMAC", NULL, "SHA256", NULL, key, key_len, data, data_len, out, out_size, &out_len);
-  ```
 
-## Secure Crypto Implementation Pattern
+
+// Example: Secure replacement for HMAC-SHA1
+```c
+EVP_Q_MAC(NULL, "HMAC", NULL, "SHA256", NULL, key, key_len, data, data_len, out, out_size, &out_len);
+```
+
+## 6. Secure Crypto Implementation Pattern
+
+
+// Example: Secure AES-256-GCM encryption (PQC-Ready Symmetric Strength)
 ```c
-// Example: Secure AES encryption
 EVP_CIPHER_CTX *ctx = EVP_CIPHER_CTX_new();
 if (!ctx) handle_error();
 
+// Use AES-256-GCM
 if (EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, key, iv) != 1)
     handle_error();
 
@@ -124,11 +135,3 @@ ciphertext_len += len;
 
 EVP_CIPHER_CTX_free(ctx);
 ```
-
-## Code Review Checklist
-- [ ] No deprecated SSL/crypto APIs used
-- [ ] No banned algorithms (MD5, DES, RC4, etc.)
-- [ ] HMAC uses SHA-256 or stronger (not SHA1)
-- [ ] All crypto operations use EVP high-level APIs
-- [ ] Proper error handling for all crypto operations
-- [ ] Key material properly zeroed after use