` \n* **JavaScript Context:** Avoid dynamic JavaScript generation; use data attributes and event listeners instead\n* **CSS Context:** Validate CSS values against strict allow-lists before injection\n* **URL Context:** Encode URLs and validate protocols to prevent `javascript:` URLs\n\n* **ARIA Attributes & SVG Context:** Validate ARIA values against allow-lists; sanitize SVG with DOMPurify SVG profiles\n* **JavaScript Event Handlers:** Never inject user data into `onclick` attributes; use `addEventListener()` instead\n\n#### 2. Leverage Framework Protections\n\nModern frameworks provide built-in XSS protections:\n\n* **React:** Auto-escapes values in JSX, but be careful with `dangerouslySetInnerHTML`\n* **Angular:** Uses contextual auto-escaping, but be cautious with `[innerHTML]` binding\n* **Vue:** Auto-escapes mustache interpolations, but watch out for `v-html`\n\nWhen using escape hatches like `dangerouslySetInnerHTML`, `[innerHTML]`, or `v-html`, always sanitize with DOMPurify first.\n\n#### 3. Server-Side Input Validation and Sanitization\n\n* **Server-Side Validation is Mandatory:** All input validation must happen on the server. Client-side validation is for user experience only.\n* **Validate Against Allow-Lists:** Use strict regex patterns for expected input types (email, username, etc.) with length limits.\n* **HTML Sanitization with Trusted Libraries:** Use [DOMPurify](https://github.com/cure53/DOMPurify) with strict configurations:\n ```javascript\n const cleanHtml = DOMPurify.sanitize(userHtml, {\n ALLOWED_TAGS: ['b', 'i', 'p', 'a', 'ul', 'li'],\n ALLOWED_ATTR: ['href', 'target', 'rel'],\n ALLOW_DATA_ATTR: false\n });\n ```\n\n#### 4. Defense-in-Depth Controls\n\n* **Content Security Policy (CSP):** Implement strict CSP headers as additional protection:\n ```http\n Content-Security-Policy: default-src 'self'; \n script-src 'self' 'nonce-{random}'; \n style-src 'self' 'unsafe-inline'; \n object-src 'none'; \n base-uri 'self';\n require-trusted-types-for 'script';\n ```\n\n* **Trusted Types API:** Use Trusted Types to prevent DOM XSS:\n ```javascript\n // Define trusted types policy\n const policy = trustedTypes.createPolicy('myPolicy', {\n createHTML: (string) => DOMPurify.sanitize(string),\n createScript: () => { throw new Error('Script creation not allowed'); }\n });\n \n // Use with trusted types\n element.innerHTML = policy.createHTML(userInput);\n ```\n\n* **Safe DOM APIs:** Always prefer safe DOM manipulation methods:\n ```javascript\n // Safe approaches\n element.textContent = userInput; // Always safe for text\n element.setAttribute('data-user', userInput); // Safe for most attributes\n element.classList.add(validatedClassName); // Safe for CSS classes\n ```\n\n* **Secure Cookie Configuration:** Prevent cookie theft:\n ```http\n Set-Cookie: sessionId=abc123; HttpOnly; Secure; SameSite=Strict\n ```\n\n#### 5. Common Pitfalls to Avoid\n\n* **Don't trust any data source:** Even internal APIs or databases can contain malicious data.\n* **Beware of indirect inputs:** User data can enter your application through URLs, form fields, HTTP headers, and JSON/XML payloads.\n* **Don't rely on client-side sanitization alone:** Always re-validate and sanitize on the server.\n* **Keep dependencies updated:** Regularly update your frameworks and libraries to benefit from security patches.\n\nBy applying these context-specific encoding strategies and defense-in-depth approaches, you can significantly reduce the risk of XSS vulnerabilities in your web applications."
},
{
"path": "sources/owasp/codeguard-0-cryptographic-storage.md",
"content": "---\ndescription: Cryptographic Storage Best Practices\nlanguages:\n- c\n- go\n- java\n- javascript\n- kotlin\n- matlab\n- python\n- ruby\n- swift\n- typescript\nalwaysApply: false\n---\n\n## Introduction\n\nThis rule provides a simple model to follow when implementing solutions to protect data at rest.\n\nPasswords should not be stored using reversible encryption - secure password hashing algorithms should be used instead. The [Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) contains further guidance on storing passwords.\n\n## Rule 1: Architectural Design Requirements\n\n**YOU MUST consider the overall architecture** of the system, as this will have a huge impact on the technical implementation.\n\n* **Application level** - REQUIRED for database compromise protection\n* **Database level** (SQL Server TDE) - Additional data-at-rest protection \n* **Filesystem level** (BitLocker, LUKS) - Physical theft protection\n* **Hardware level** (encrypted RAID/SSDs) - Hardware-based protection\n\n**YOU MUST minimize sensitive data storage** - avoid storing credit card details and implement data minimization policies. Use tokenization when storage is unavoidable.\n\n## Rule 2: Algorithm Requirements\n\n**YOU MUST use approved algorithms:**\n* **Symmetric:** AES with ≥128-bit keys (256-bit preferred)\n* **Asymmetric:** Curve25519 (ECC preferred) or RSA ≥2048 bits\n* **Custom algorithms:** PROHIBITED\n\n**YOU MUST use authenticated cipher modes:**\n1. **GCM** or **CCM** (preferred)\n2. **CTR/CBC** only with separate authentication (Encrypt-then-MAC)\n3. **ECB:** PROHIBITED\n\n**For RSA: YOU MUST enable Random Padding** (OAEP/PKCS#1).\n\n**YOU MUST use cryptographically secure random generators:**\n\n| Platform | PROHIBITED | REQUIRED |\n|----------|------------|----------|\n| PHP | `rand()`, `mt_rand()` | `random_bytes()`, `random_int()` |\n| Java | `java.util.Random` | `java.security.SecureRandom` |\n| .NET | `System.Random` | `System.Security.Cryptography.RandomNumberGenerator` |\n| Python | `random` module | `secrets` module |\n| JavaScript | `Math.random()` | `window.crypto.getRandomValues()` |\n| Go | `math/rand` | `crypto/rand` |\n| Node.js | `Math.random()` | `crypto.randomBytes()`, `crypto.randomInt()` |\n\n**UUIDs:** Version 1 UUIDs are NOT random. Only trust Version 4 UUIDs if implementation uses CSPRNG.\n\n## Rule 3: Key Management Requirements\n\n**YOU MUST implement formal processes for:**\n* Key generation using cryptographically secure functions\n* Secure key distribution and deployment\n* Regular key rotation and secure decommissioning\n\n**Key Generation:** YOU ARE PROHIBITED from using passwords, phrases, or predictable patterns. Multiple keys MUST be fully independent.\n\n**Key Rotation Requirements - YOU MUST rotate keys when:**\n* Key compromise is suspected\n* Cryptoperiod expires (see NIST SP 800-57)\n* Usage limits reached (2^35 bytes for 64-bit keys, 2^68 bytes for 128-bit)\n* Algorithm security changes\n\n**YOU MUST have rotation processes ready BEFORE compromise.**\n\n## Rule 4: Key Storage Requirements\n\n**YOU MUST use secure storage mechanisms where available:**\n* Physical/Virtual HSMs\n* Cloud key vaults (AWS KMS, Azure Key Vault, Google Cloud KMS)\n* External secrets management (HashiCorp Vault, Conjur)\n* Framework secure APIs (ProtectedData, Keychain)\n\n**Basic Storage Rules (when secure mechanisms unavailable):**\n* PROHIBITED: Hard-coding keys in source code or version control\n* REQUIRED: Restrictive permissions on config files\n* AVOID: Environment variables (exposure risk)\n\n**Key Separation:** YOU MUST store keys separately from encrypted data where possible.\n\n**Key Encryption:** YOU MUST encrypt stored keys using separate Key Encryption Keys (KEK):\n* Data Encryption Key (DEK) encrypts data\n* Key Encryption Key (KEK) encrypts DEK\n* KEK MUST be stored separately and be ≥ as strong as DEK\n\n## Rule 5: Defense in Depth Requirements\n\n**YOU MUST design applications to be secure even if cryptographic controls fail:**\n* Additional security layers for encrypted information\n* Strong access control (not relying on encrypted URL parameters alone)\n* Logging and monitoring of encrypted data access\n\n## Critical Security Requirements\n\n**COMPLIANCE IS MANDATORY** for all systems handling sensitive data.\n\n**YOU ARE ABSOLUTELY PROHIBITED FROM:**\n* Implementing custom cryptographic algorithms\n* Using insecure random generators for security purposes\n* Hard-coding encryption keys in source code\n* Using deprecated algorithms (MD5, SHA-1, DES, RC4)\n* Storing keys with encrypted data without proper separation\n\n**YOU MUST ALWAYS:**\n* Use authenticated encryption modes where available\n* Generate unique, random keys for each operation\n* Implement proper key lifecycle management\n* Use vetted cryptographic libraries only\n* Test key rotation procedures before needed"
},
{
"path": "sources/owasp/codeguard-0-cw-cryptographic-security-guidelines.md",
"content": "---\ndescription: Cryptographic Security Guidelines\nlanguages:\n- c\nalwaysApply: false\n---\n\n### Cryptographic Security Guidelines\n\n#### Deprecated SSL/Crypto APIs - FORBIDDEN\n**NEVER use these deprecated functions. Use the replacement APIs listed below:**\n\n##### Symmetric Encryption (AES)\n- **Deprecated**: `AES_encrypt()`, `AES_decrypt()`\n- **Replacement**: Use EVP high-level APIs:\n ```c\n EVP_EncryptInit_ex()\n EVP_EncryptUpdate()\n EVP_EncryptFinal_ex()\n EVP_DecryptInit_ex()\n EVP_DecryptUpdate()\n EVP_DecryptFinal_ex()\n ```\n\n##### RSA Operations\n- **Deprecated**: `RSA_new()`, `RSA_up_ref()`, `RSA_free()`, `RSA_set0_crt_params()`, `RSA_get0_n()`\n- **Replacement**: Use EVP key management APIs:\n ```c\n EVP_PKEY_new()\n EVP_PKEY_up_ref()\n EVP_PKEY_free()\n ```\n\n##### Hash Functions\n- **Deprecated**: `SHA1_Init()`, `SHA1_Update()`, `SHA1_Final()`\n- **Replacement**: Use EVP digest APIs:\n ```c\n EVP_DigestInit_ex()\n EVP_DigestUpdate()\n EVP_DigestFinal_ex()\n EVP_Q_digest() // For simple one-shot hashing\n ```\n\n##### MAC Operations\n- **Deprecated**: `CMAC_Init()`, `HMAC()` (especially with SHA1)\n- **Replacement**: Use EVP MAC APIs:\n ```c\n EVP_Q_MAC() // For simple MAC operations\n ```\n\n##### Key Wrapping\n- **Deprecated**: `AES_wrap_key()`, `AES_unwrap_key()`\n- **Replacement**: Use EVP key wrapping APIs or implement using EVP encryption\n\n##### Other Deprecated Functions\n- **Deprecated**: `DSA_sign()`, `DH_check()`\n- **Replacement**: Use corresponding EVP APIs for DSA and DH operations\n\n#### Banned Insecure Algorithms - STRICTLY FORBIDDEN\n**These algorithms MUST NOT be used in any form:**\n\n##### Hash Algorithms (Banned)\n- MD2, MD4, MD5, SHA-0\n- **Reason**: Cryptographically broken, vulnerable to collision attacks\n- **Use Instead**: SHA-256, SHA-384, SHA-512\n\n##### Symmetric Ciphers (Banned)\n- RC2, RC4, Blowfish, DES, 3DES\n- **Reason**: Weak key sizes, known vulnerabilities\n- **Use Instead**: AES-128, AES-256, ChaCha20\n\n##### Key Exchange (Banned)\n- Static RSA key exchange\n- Anonymous Diffie-Hellman\n- **Reason**: No forward secrecy, vulnerable to man-in-the-middle attacks\n- **Use Instead**: ECDHE, DHE with proper validation\n\n#### Broccoli Project Specific Requirements\n- **HMAC() with SHA1**: Deprecated per Broccoli project requirements\n- **Replacement**: Use HMAC with SHA-256 or stronger:\n ```c\n // Instead of HMAC() with SHA1\n EVP_Q_MAC(NULL, \"HMAC\", NULL, \"SHA256\", NULL, key, key_len, data, data_len, out, out_size, &out_len);\n ```\n\n#### Secure Crypto Implementation Pattern\n```c\n// Example: Secure AES encryption\nEVP_CIPHER_CTX *ctx = EVP_CIPHER_CTX_new();\nif (!ctx) handle_error();\n\nif (EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, key, iv) != 1)\n handle_error();\n\nint len, ciphertext_len;\nif (EVP_EncryptUpdate(ctx, ciphertext, &len, plaintext, plaintext_len) != 1)\n handle_error();\nciphertext_len = len;\n\nif (EVP_EncryptFinal_ex(ctx, ciphertext + len, &len) != 1)\n handle_error();\nciphertext_len += len;\n\nEVP_CIPHER_CTX_free(ctx);\n```\n\n#### Code Review Checklist\n- [ ] No deprecated SSL/crypto APIs used\n- [ ] No banned algorithms (MD5, DES, RC4, etc.)\n- [ ] HMAC uses SHA-256 or stronger (not SHA1)\n- [ ] All crypto operations use EVP high-level APIs\n- [ ] Proper error handling for all crypto operations\n- [ ] Key material properly zeroed after use"
},
{
"path": "sources/owasp/codeguard-0-cw-memory-string-usage-guidelines.md",
"content": "---\ndescription: Memory and String Safety Guidelines\nlanguages:\n- c\nalwaysApply: false\n---\n\n### Memory and String Safety Guidelines\n\n#### Unsafe Memory Functions - FORBIDDEN\n**NEVER use these unsafe memory functions that don't check input parameter boundaries:**\n\n##### Banned Memory Functions:\n- `memcpy()` → Use `memcpy_s()`\n- `memset()` → Use `memset_s()`\n- `memmove()` → Use `memmove_s()`\n- `memcmp()` → Use `memcmp_s()`\n- `bzero()` → Use `memset_s()`\n- `memzero()` → Use `memset_s()`\n\n##### Safe Memory Function Replacements:\n```c\n// Instead of: memcpy(dest, src, count);\nerrno_t result = memcpy_s(dest, dest_size, src, count);\nif (result != 0) {\n// Handle error\n}\n\n// Instead of: memset(dest, value, count);\nerrno_t result = memset_s(dest, dest_size, value, count);\n\n// Instead of: memmove(dest, src, count);\nerrno_t result = memmove_s(dest, dest_size, src, count);\n\n// Instead of: memcmp(s1, s2, count);\nint indicator;\nerrno_t result = memcmp_s(s1, s1max, s2, s2max, count, &indicator);\nif (result == 0) {\n// indicator contains comparison result: <0, 0, or >0\n}\n```\n\n#### Unsafe String Functions - FORBIDDEN\n**NEVER use these unsafe string functions that can cause buffer overflows:**\n\n##### Banned String Functions:\n- `strstr()` → Use `strstr_s()`\n- `strtok()` → Use `strtok_s()`\n- `strcpy()` → Use `strcpy_s()`\n- `strcmp()` → Use `strcmp_s()`\n- `strlen()` → Use `strnlen_s()`\n- `strcat()` → Use `strcat_s()`\n- `sprintf()` → Use `snprintf()`\n\n##### Safe String Function Replacements:\n```c\n// String Search\nerrno_t strstr_s(char *dest, rsize_t dmax, const char *src, rsize_t slen, char **substring);\n\n// String Tokenization\nchar *strtok_s(char *dest, rsize_t *dmax, const char *src, char **ptr);\n\n// String Copy\nerrno_t strcpy_s(char *dest, rsize_t dmax, const char *src);\n\n// String Compare\nerrno_t strcmp_s(const char *dest, rsize_t dmax, const char *src, int *indicator);\n\n// String Length (bounded)\nrsize_t strnlen_s(const char *str, rsize_t strsz);\n\n// String Concatenation\nerrno_t strcat_s(char *dest, rsize_t dmax, const char *src);\n\n// Formatted String (always use size-bounded version)\nint snprintf(char *s, size_t n, const char *format, ...);\n```\n\n#### Implementation Examples:\n\n##### Safe String Copy Pattern:\n```c\n// Bad - unsafe\nchar dest[256];\nstrcpy(dest, src); // Buffer overflow risk!\n\n// Good - safe\nchar dest[256];\nerrno_t result = strcpy_s(dest, sizeof(dest), src);\nif (result != 0) {\n// Handle error: src too long or invalid parameters\nEWLC_LOG_ERROR(\"String copy failed: %d\", result);\nreturn ERROR;\n}\n```\n\n##### Safe String Concatenation Pattern:\n```c\n// Bad - unsafe\nchar buffer[256] = \"prefix_\";\nstrcat(buffer, suffix); // Buffer overflow risk!\n\n// Good - safe\nchar buffer[256] = \"prefix_\";\nerrno_t result = strcat_s(buffer, sizeof(buffer), suffix);\nif (result != 0) {\nEWLC_LOG_ERROR(\"String concatenation failed: %d\", result);\nreturn ERROR;\n}\n```\n\n##### Safe Memory Copy Pattern:\n```c\n// Bad - unsafe\nmemcpy(dest, src, size); // No boundary checking!\n\n// Good - safe\nerrno_t result = memcpy_s(dest, dest_max_size, src, size);\nif (result != 0) {\nEWLC_LOG_ERROR(\"Memory copy failed: %d\", result);\nreturn ERROR;\n}\n```\n\n##### Safe String Tokenization Pattern:\n```c\n// Bad - unsafe\nchar *token = strtok(str, delim); // Modifies original string unsafely\n\n// Good - safe\nchar *next_token = NULL;\nrsize_t str_max = strnlen_s(str, MAX_STRING_SIZE);\nchar *token = strtok_s(str, &str_max, delim, &next_token);\nwhile (token != NULL) {\n// Process token\ntoken = strtok_s(NULL, &str_max, delim, &next_token);\n}\n```\n\n#### Memory and String Safety Code Review Checklist:\n\n##### Pre-Code Review (Developer):\n- [ ] No unsafe memory functions (`memcpy`, `memset`, `memmove`, `memcmp`, `bzero`)\n- [ ] No unsafe string functions (`strcpy`, `strcat`, `strcmp`, `strlen`, `sprintf`, `strstr`, `strtok`)\n- [ ] All memory operations use `*_s()` variants with proper size parameters\n- [ ] Buffer sizes are correctly calculated using `sizeof()` or known limits\n- [ ] No hardcoded buffer sizes that could change\n\n##### Code Review (Reviewer):\n- [ ] **Memory Safety**: Verify all memory operations use safe variants\n- [ ] **Buffer Bounds**: Confirm destination buffer sizes are properly specified\n- [ ] **Error Handling**: Check that all `errno_t` return values are handled\n- [ ] **Size Parameters**: Validate that `rsize_t dmax` parameters are correct\n- [ ] **String Termination**: Ensure strings are properly null-terminated\n- [ ] **Length Validation**: Check that source string lengths are validated before operations\n\n##### Static Analysis Integration:\n- [ ] Enable compiler warnings for unsafe function usage\n- [ ] Use static analysis tools to detect unsafe function calls\n- [ ] Configure build system to treat unsafe function warnings as errors\n- [ ] Add pre-commit hooks to scan for banned functions\n\n#### Common Pitfalls and Solutions:\n\n##### Pitfall 1: Wrong Size Parameter\n```c\n// Wrong - using source size instead of destination size\nstrcpy_s(dest, strlen(src), src); // WRONG!\n\n// Correct - using destination buffer size\nstrcpy_s(dest, sizeof(dest), src); // CORRECT\n```\n\n##### Pitfall 2: Ignoring Return Values\n```c\n// Wrong - ignoring potential errors\nstrcpy_s(dest, sizeof(dest), src); // Error not checked\n\n// Correct - checking return value\nif (strcpy_s(dest, sizeof(dest), src) != 0) {\n// Handle error appropriately\n}\n```\n\n##### Pitfall 3: Using sizeof() on Pointers\n```c\n// Wrong - sizeof pointer, not buffer\nvoid func(char *buffer) {\nstrcpy_s(buffer, sizeof(buffer), src); // sizeof(char*) = 8!\n}\n\n// Correct - pass buffer size as parameter\nvoid func(char *buffer, size_t buffer_size) {\nstrcpy_s(buffer, buffer_size, src);\n}\n```"
},
{
"path": "sources/owasp/codeguard-0-database-security.md",
"content": "---\ndescription: Database Security Best Practices\nlanguages:\n- c\n- java\n- javascript\n- python\n- sql\n- yaml\nalwaysApply: false\n---\n\n## Database Security Guidelines\n\nThis rule advises on securely configuring SQL and NoSQL databases to protect against data breaches and unauthorized access:\n\n- Backend Database Protection\n - Isolate database servers from other systems and limit host connections.\n - Disable network (TCP) access when possible; use local socket files or named pipes.\n - Configure database to bind only on localhost when appropriate.\n - Restrict network port access to specific hosts with firewall rules.\n - Place database server in separate DMZ isolated from application server.\n - Never allow direct connections from thick clients to backend database.\n\n- Transport Layer Security\n - Configure database to only allow encrypted connections.\n - Install trusted digital certificates on database servers.\n - Use TLSv1.2+ with modern ciphers (AES-GCM, ChaCha20) for client connections.\n - Verify digital certificate validity in client applications.\n - Ensure all database traffic is encrypted, not just initial authentication.\n\n- Secure Authentication Configuration\n - Always require authentication, including from local server connections.\n - Protect accounts with strong, unique passwords.\n - Use dedicated accounts per application or service.\n - Configure minimum required permissions only.\n - Regularly review accounts and permissions.\n - Remove accounts when applications are decommissioned.\n - Change passwords when staff leave or compromise is suspected.\n\n- Database Credential Storage\n - Never store credentials in application source code.\n - Store credentials in configuration files outside web root.\n - Set appropriate file permissions for credential access.\n - Never check credential files into source code repositories.\n - Encrypt credential storage using built-in functionality when available.\n - Use environment variables or secrets management solutions.\n\n- Secure Permission Management\n - Apply principle of least privilege to all database accounts.\n - Do not use built-in root, sa, or SYS accounts.\n - Do not grant administrative rights to application accounts.\n - Restrict account connections to allowed hosts only.\n - Use separate databases and accounts for Development, UAT, and Production.\n - Grant only required permissions (SELECT, UPDATE, DELETE as needed).\n - Avoid making accounts database owners to prevent privilege escalation.\n - Implement table-level, column-level, and row-level permissions when needed.\n\n- Database Configuration and Hardening\n - Install required security updates and patches regularly.\n - Run database services under low-privileged user accounts.\n - Remove default accounts and sample databases.\n - Store transaction logs on separate disk from main database files.\n - Configure regular encrypted database backups with proper permissions.\n - Disable unnecessary stored procedures and dangerous features.\n - Implement database activity monitoring and alerting.\n\n- Platform-Specific Hardening\n - SQL Server: Disable xp_cmdshell, CLR execution, SQL Browser service, Mixed Mode Authentication (unless required).\n - MySQL/MariaDB: Run mysql_secure_installation, disable FILE privilege for users.\n - PostgreSQL: Follow PostgreSQL security documentation guidelines.\n - MongoDB: Implement MongoDB security checklist requirements.\n - Redis: Follow Redis security guide recommendations.\n\nSummary: \nIsolate database systems, enforce encrypted connections, implement strong authentication, store credentials securely using secrets management, apply least privilege permissions, harden database configurations, and maintain regular security updates and monitoring."
},
{
"path": "sources/owasp/codeguard-0-deserialization.md",
"content": "---\ndescription: Deserialization Security Best Practices\nlanguages:\n- c\n- java\n- javascript\n- php\n- python\n- xml\n- yaml\nalwaysApply: false\n---\n\n## Avoid Unsafe Deserialization of Untrusted Data\n\nDeserialization of untrusted input can lead to critical vulnerabilities such as remote code execution, denial of service, and privilege escalation. This rule ensures developers follow best practices to safely handle serialization and deserialization operations.\n\nRequirements:\n\n- Always treat incoming serialized data from untrusted sources as hostile.\n- Validate input size, structure, and content before deserialization.\n- Prefer standardized, safe data formats like JSON or XML without type metadata over native serialization formats.\n- For XML: disable DTDs and external entities to prevent XXE attacks.\n- Avoid using unsafe native serialization APIs on untrusted input, such as:\n - PHP: avoid `unserialize()`, use `json_decode()`/`json_encode()` instead.\n - Python: avoid `pickle.loads`, `yaml.load` (use `safe_load`), and `jsonpickle` on untrusted data.\n - Java: override `ObjectInputStream#resolveClass()` to allowlist classes; mark sensitive fields `transient`; avoid polymorphic deserialization unless strictly allowlisted.\n - .NET: avoid `BinaryFormatter`; use `DataContractSerializer` or `XmlSerializer`; set `TypeNameHandling = None` in JSON.Net; never trust deserialized types blindly.\n- Sign serialized data and verify signatures to ensure integrity before deserialization.\n- Configure serialization libraries securely:\n - Jackson: `mapper.enableDefaultTyping(ObjectMapper.DefaultTyping.NON_FINAL)` is dangerous\n - fastjson: Enable safemode, disable autotype\n - XStream: Use allowlists with `XStream.allowTypes()`\n - SnakeYAML: Use `yaml.safe_load()` instead of `yaml.load()`\n - Keep dependencies updated to fixed versions.\n- Reject or safely handle polymorphic or complex objects deserialization from untrusted sources.\n- Use hardened deserialization agents/tools (e.g., SerialKiller, hardened ObjectInputStream subclasses, JVM agents).\n- Log deserialization attempts and monitor for suspicious activity.\n- Regularly scan code and dependencies for unsafe deserialization patterns using static and dynamic analysis tools.\n\nSecurity Impact:\n\nDeserialization attacks are a frequently exploited vector leading to severe security impacts. Following these practices prevents attackers from injecting malicious objects or payloads that the application may execute.\n\nExamples:\n\nAvoid:\n- PHP: calling `unserialize($data)` on external input.\n- Java: deserializing classes without strict allowlisting or type validation.\n- Python: loading YAML with `yaml.load()` on untrusted data.\n- .NET: using `BinaryFormatter.Deserialize()` on untrusted input.\n- XML: processing XML with DTDs enabled or external entity resolution.\n\nRecommended:\n- PHP: use `json_decode()` and validate JSON schema.\n- Java: Override `resolveClass()` to allowlist safe classes:\n ```java\n @Override\n protected Class resolveClass(ObjectStreamClass desc) throws IOException, ClassNotFoundException {\n if (!allowedClasses.contains(desc.getName())) {\n throw new InvalidClassException(\"Unauthorized class\", desc.getName());\n }\n return super.resolveClass(desc);\n }\n ```\n- Python: Use safe YAML loading:\n ```python\n import yaml\n data = yaml.safe_load(input) # Safe\n # Never: yaml.load(input) # Dangerous\n ```\n- .NET: Use DataContractSerializer with type control:\n ```csharp\n // Safe approach\n var serializer = new DataContractSerializer(typeof(SafeType));\n var obj = serializer.ReadObject(stream);\n \n // JSON.NET safety\n JsonConvert.DeserializeObject
(json, new JsonSerializerSettings {\n TypeNameHandling = TypeNameHandling.None\n });\n ```\n- XML: Configure parsers safely:\n ```java\n // Java: Disable DTDs and external entities\n factory.setFeature(\"http://apache.org/xml/features/disallow-doctype-decl\", true);\n factory.setFeature(\"http://xml.org/sax/features/external-general-entities\", false);\n ```\n ```csharp\n // .NET: Disable DTD processing\n XmlReaderSettings settings = new XmlReaderSettings();\n settings.DtdProcessing = DtdProcessing.Prohibit;\n ```\n\nMonitoring Requirements:\n- Log all deserialization attempts with data size and type information\n- Alert on deserialization failures or unexpected data patterns\n- Monitor for known malicious payloads (e.g., `AC ED 00 05`, `rO0`, `AAEAAAD`)\n- Track deserialization performance to detect \"billion laughs\" attacks"
},
{
"path": "sources/owasp/codeguard-0-django-rest-framework.md",
"content": "---\ndescription: Django REST Framework Security Best Practices\nlanguages:\n- python\n- yaml\nalwaysApply: false\n---\n\n## Django REST Framework Security Guidelines\n\nThis rule advises on critical security practices when developing Django REST Framework APIs to protect against common risks:\n\n- Authentication & Authorization \n - Always set `DEFAULT_AUTHENTICATION_CLASSES` with appropriate authentication schemes for all non-public endpoints. \n - When using SessionAuthentication, ensure CSRF protection is enabled and properly configured.\n - Never leave `DEFAULT_PERMISSION_CLASSES` as `AllowAny`; explicitly restrict access using proper permission classes. \n - When overriding `get_object()`, always call `self.check_object_permissions(request, obj)` to enforce object-level access control. \n - Avoid per-view overrides of authentication, permission, or throttle classes unless fully confident in their implications.\n\n- Serializer Security \n - In DRF Serializers, specify explicit `fields = [...]` allowlists; do not use `exclude`.\n - For Django ModelForms (when used outside DRF), always use `Meta.fields` allowlist instead of `Meta.exclude` or `\"__all__\"`.\n - DO NOT use `Meta.exclude` (denylist approach) or `ModelForms.Meta.fields = \"__all__\"`.\n\n- Rate Limiting & Throttling \n - Configure `DEFAULT_THROTTLE_CLASSES` to enable API rate limiting as a DoS defense layer. \n - Prefer to enforce rate limiting at the gateway or WAF level; DRF throttling is a last-resort safeguard.\n\n- Security Configuration \n - Ensure `DEBUG` and `DEBUG_PROPAGATE_EXCEPTIONS` are set to `False` in production environments. \n - Never hardcode secrets such as `SECRET_KEY`; inject them via environment variables or secrets managers. \n - Disable all unused or dangerous HTTP methods (e.g., PUT, DELETE) at the API level. \n - Validate, sanitize, and filter all incoming data rigorously.\n - Set secure HTTP headers: `SECURE_CONTENT_TYPE_NOSNIFF = True`, `X_FRAME_OPTIONS = 'DENY'`, `SECURE_BROWSER_XSS_FILTER = True`.\n - Implement Content Security Policy (CSP) using django-csp middleware to prevent XSS and clickjacking attacks.\n\n- Prevent Injection Attacks \n - Avoid raw SQL queries with user input; use ORM or parameterized queries exclusively.\n - DO NOT add user input to dangerous methods (`raw()`, `extra()`, `cursor.execute()`).\n - For YAML parsing, use safe loaders (`yaml.SafeLoader`); never parse YAML or pickle data from untrusted sources.\n - DO NOT use `eval()`, `exec()`, or similar dynamic code execution functions on user input.\n\n- Secret Management \n - Never hardcode secrets such as `SECRET_KEY`; inject them via environment variables or secrets managers.\n - DO NOT hardcode API keys, database passwords, or other sensitive credentials in source code.\n\n- Input Validation \n - Validate, sanitize, and filter all client-provided data rigorously.\n - Use Django's built-in form validation or DRF serializers with proper validation methods.\n\n- Logging Security \n - Log authentication failures, authorization denials, and validation errors with sufficient context.\n - DO NOT log sensitive data (passwords, tokens, PII) in application logs.\n - Include stack traces, error messages, and user context in security-relevant log entries.\n\nSummary: \nAlways enforce object-level permissions with `check_object_permissions()`, use explicit field allowlists in serializers, avoid dangerous functions with user input, never hardcode secrets, implement proper input validation, and ensure security-aware logging practices."
},
{
"path": "sources/owasp/codeguard-0-django-security.md",
"content": "---\ndescription: Django Security Best Practices\nlanguages:\n- c\n- python\nalwaysApply: false\n---\n\n## Django Security Guidelines\n\nThis rule advises on critical Django security practices to prevent common web vulnerabilities:\n\n- General Security Configuration\n - Never set `DEBUG = True` in production environments.\n - Keep Django and dependencies up-to-date regularly.\n - Use rate limiting packages like `django_ratelimit` or `django-axes` for brute-force protection.\n\n- Authentication System\n - Include `django.contrib.auth`, `django.contrib.contenttypes`, and `django.contrib.sessions` in `INSTALLED_APPS`.\n - Use `@login_required` decorator to protect views requiring authentication.\n - Configure `AUTH_PASSWORD_VALIDATORS` with appropriate validators for password policies.\n - Use `make_password()` and `check_password()` functions for password hashing and verification.\n\n- Secret Key Management\n - Generate `SECRET_KEY` with at least 50 characters containing letters, digits, and symbols.\n - Use `get_random_secret_key()` function for key generation.\n - Store `SECRET_KEY` in environment variables, never hardcode in source.\n - Rotate keys regularly and immediately upon exposure.\n\n- Security Middleware Configuration\n - Include `django.middleware.security.SecurityMiddleware` in `MIDDLEWARE` settings.\n - Include `django.middleware.clickjacking.XFrameOptionsMiddleware` in `MIDDLEWARE` settings.\n - Set `SECURE_CONTENT_TYPE_NOSNIFF = True` for MIME type protection.\n - Configure `SECURE_HSTS_SECONDS` with positive integer for HTTPS enforcement.\n - Set `X_FRAME_OPTIONS = 'DENY'` or `'SAMEORIGIN'` for clickjacking protection.\n\n- Cookie Security\n - Set `SESSION_COOKIE_SECURE = True` to send session cookies over HTTPS only.\n - Set `CSRF_COOKIE_SECURE = True` to send CSRF cookies over HTTPS only.\n - Use `secure=True` parameter when setting custom cookies with `HttpResponse.set_cookie()`.\n\n- CSRF Protection\n - Include `django.middleware.csrf.CsrfViewMiddleware` in `MIDDLEWARE` settings.\n - Use `{% csrf_token %}` template tag in all forms.\n - Extract CSRF token properly for AJAX calls.\n\n- XSS Protection\n - Use Django's built-in template system with automatic HTML escaping.\n - Avoid `safe` filter and `mark_safe` function unless input is from trusted sources.\n - Use `json_script` template filter for passing data to JavaScript.\n\n- HTTPS Configuration\n - Set `SECURE_SSL_REDIRECT = True` to redirect HTTP requests to HTTPS.\n - Configure `SECURE_PROXY_SSL_HEADER` when behind proxy or load balancer.\n\n- Admin Panel Security\n - Change default admin URL from `/admin/` to custom path in `urls.py`.\n\nCode Examples (from OWASP):\n\n```python\n# Authentication setup\nINSTALLED_APPS = [\n 'django.contrib.auth',\n 'django.contrib.contenttypes',\n 'django.contrib.sessions',\n]\n\n@login_required\ndef my_view(request):\n # Your view logic\n\n# Password validation\nAUTH_PASSWORD_VALIDATORS = [\n {\n 'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',\n },\n {\n 'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',\n 'OPTIONS': {\n 'min_length': 8,\n }\n },\n]\n\n# Secret key from environment\nSECRET_KEY = os.environ.get('DJANGO_SECRET_KEY')\n\n# Cookie security\nresponse.set_cookie('my_cookie', 'cookie_value', secure=True)\n```\n\n```html\n\n\n```\n\nSummary: \nConfigure Django securely by disabling debug mode in production, using proper authentication settings, securing secret keys, enabling security middleware, setting secure cookie attributes, implementing CSRF protection, preventing XSS, enforcing HTTPS, and securing admin access."
},
{
"path": "sources/owasp/codeguard-0-docker-security.md",
"content": "---\ndescription: Docker Security Best Practices\nlanguages:\n- docker\n- yaml\nalwaysApply: false\n---\n\n## Docker Security Guidelines\n\nThis rule advises on critical Docker container security practices to protect against common risks:\n\n- Container User Security\n - Always specify a non-root user in Dockerfiles using `USER` directive.\n - Never run containers as root; use `docker run -u ` or Kubernetes `securityContext.runAsUser`.\n - Avoid `USER root` or missing `USER` directives in Dockerfiles.\n\n- Docker Daemon Socket Protection\n - DO NOT expose `/var/run/docker.sock` to containers via volume mounts.\n - DO NOT enable TCP Docker daemon socket (`-H tcp://0.0.0.0:XXX`) without TLS.\n - Avoid `- \"/var/run/docker.sock:/var/run/docker.sock\"` in docker-compose files.\n\n- Capability and Privilege Management\n - Drop all capabilities (`--cap-drop all`) and add only required ones (`--cap-add`).\n - DO NOT use `--privileged` flag in container configurations.\n - Set `allowPrivilegeEscalation: false` in Kubernetes security contexts.\n - Use `--security-opt=no-new-privileges` to prevent privilege escalation.\n\n- Dockerfile Security Practices\n - Pin base image versions (avoid `latest` tags in production).\n - Use `COPY` instead of `ADD` when not extracting archives.\n - DO NOT include secrets, passwords, or API keys in Dockerfiles.\n - Avoid curl bashing in `RUN` directives; use package managers when possible.\n - Include `HEALTHCHECK` instructions for container health monitoring.\n\n- Resource and Filesystem Security\n - Limit container resources (memory, CPU) in docker-compose or Kubernetes specs.\n - Use read-only root filesystems (`--read-only` or `readOnlyRootFilesystem: true`).\n - Mount volumes as read-only (`:ro`) when write access is not needed.\n - Use `--tmpfs` for temporary writable storage instead of persistent volumes.\n\n- Network and Runtime Security\n - Avoid default bridge networking; define custom Docker networks.\n - DO NOT share host network namespace (`--net=host`).\n - DO NOT expose unnecessary ports in Dockerfiles or container configs.\n - Enable default security profiles (seccomp, AppArmor, SELinux); do not disable them.\n\n- Secret Management\n - Use Docker Secrets or Kubernetes encrypted secrets for sensitive data.\n - DO NOT embed secrets in environment variables or Dockerfile layers.\n - Avoid hardcoded credentials in container configurations.\n\n- Container Image Security\n - Scan images for vulnerabilities before deployment.\n - Use minimal base images (alpine, distroless) to reduce attack surface.\n - Remove package managers and unnecessary tools from production images.\n\nSummary: \nAlways run containers as non-root users, never expose Docker daemon socket, drop unnecessary capabilities, use secure Dockerfile practices, implement resource limits and read-only filesystems, configure proper networking, manage secrets securely, and scan images for vulnerabilities."
},
{
"path": "sources/owasp/codeguard-0-dom-based-xss-prevention.md",
"content": "---\ndescription: DOM-based XSS Prevention Best Practices\nlanguages:\n- c\n- html\n- javascript\n- php\n- typescript\n- vlang\nalwaysApply: false\n---\n\n## DOM-based XSS Prevention Security Rule\n\n**RULE ENFORCEMENT:** This rule prevents DOM-based XSS vulnerabilities where untrusted data from user-controllable sources is inserted into DOM sinks without proper encoding or sanitization.\n\n## Rule 1: DOM Sink Restrictions by Context\n\n**YOU MUST secure DOM sinks** based on risk level:\n\n### High-Risk HTML Sinks\n\n```javascript\n// VIOLATION: Direct assignment to HTML sinks\nelement.innerHTML = userInput; // DANGEROUS\nelement.outerHTML = userInput; // DANGEROUS\ndocument.write(userInput); // DANGEROUS\n\n// REQUIRED: Use safe alternatives\nelement.textContent = userInput; // SAFE\nelement.innerHTML = DOMPurify.sanitize(userInput); // SAFE\n```\n\n### Critical JavaScript Execution Sinks\n\n```javascript\n// VIOLATION: Code execution sinks\neval(userInput); // CRITICAL VULNERABILITY\nnew Function(userInput); // CRITICAL VULNERABILITY\nsetTimeout(userInput, 100); // CRITICAL VULNERABILITY\n\n// REQUIRED: Safe alternatives\nsetTimeout(() => processData(userInput), 100); // SAFE\nJSON.parse(userInput); // SAFE for JSON\n```\n\n### Medium-Risk URL/Event Sinks\n\n```javascript\n// VIOLATION: Unvalidated assignments\nlocation.href = userInput; // DANGEROUS\nelement.onclick = userInput; // DANGEROUS\n\n// REQUIRED: Validate and use safe patterns\nif (/^https?:\\/\\/trusted-domain\\.com/.test(userInput)) {\n location.href = encodeURI(userInput);\n}\nelement.addEventListener('click', () => handleClick(userInput));\n```\n\n## Rule 2: Mandatory CSP and Trusted Types\n\n**YOU MUST implement strict CSP:**\n\n```http\nContent-Security-Policy: \n script-src 'self' 'nonce-{random}';\n object-src 'none';\n base-uri 'self';\n require-trusted-types-for 'script';\n```\n\n**YOU MUST use Trusted Types:**\n\n```javascript\nconst policy = trustedTypes.createPolicy('dom-xss-prevention', {\n createHTML: (string) => DOMPurify.sanitize(string, {\n ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p', 'br'],\n ALLOWED_ATTR: []\n })\n});\nelement.innerHTML = policy.createHTML(userInput);\n```\n\n## Rule 3: Server-Side Validation Requirements\n\n**YOU MUST validate all user input server-side:**\n\n```javascript\nfunction validateInput(input, context) {\n if (input.length > 1000) throw new Error('Input too long');\n \n const patterns = {\n html: /]*>/g\n };\n \n if (patterns[context] && patterns[context].test(input)) {\n throw new Error('Invalid input detected');\n }\n return input;\n}\n```\n\n## Rule 4: Context-Aware Encoding\n\n**YOU MUST apply proper encoding by context:**\n\n```javascript\n// HTML Context\nfunction encodeHTML(str) {\n return str.replace(/[&<>\"'\\/]/g, char => ({\n '&': '&', '<': '<', '>': '>', '\"': '"', \"'\": ''', '/': '/'\n })[char]);\n}\n\n// JavaScript Context \nfunction encodeJS(str) {\n return str.replace(/[\\\\'\"<>/\\n\\r\\t]/g, char => ({\n '\\\\': '\\\\\\\\', \"'\": \"\\\\'\", '\"': '\\\\\"', '<': '\\\\u003C', \n '>': '\\\\u003E', '/': '\\\\u002F', '\\n': '\\\\n', '\\r': '\\\\r', '\\t': '\\\\t'\n })[char]);\n}\n\n// URL Context\nfunction encodeURL(str) {\n return encodeURIComponent(str).replace(/['\"<>]/g, char => \n '%' + char.charCodeAt(0).toString(16).toUpperCase());\n}\n```\n\n## Rule 5: Safe DOM API Usage\n\n**YOU MUST use safe DOM construction:**\n\n```javascript\nfunction createSafeElement(tagName, textContent, attributes = {}) {\n const element = document.createElement(tagName);\n if (textContent) element.textContent = textContent;\n \n const safeAttrs = ['class', 'id', 'title', 'alt', 'src', 'href', 'role'];\n for (const [key, value] of Object.entries(attributes)) {\n if (safeAttrs.includes(key.toLowerCase())) {\n element.setAttribute(key, value);\n }\n }\n return element;\n}\n```\n\n## Rule 6: Source Validation\n\n**YOU MUST validate untrusted data sources:**\n\n### URL Parameters & PostMessage\n\n```javascript\n// URL parameter validation\nfunction getURLParam(name) {\n const value = new URLSearchParams(location.search).get(name);\n if (!value || value.length > 100 || / {\n const allowedOrigins = ['https://trusted-domain.com'];\n if (!allowedOrigins.includes(event.origin)) return;\n processMessage(event.data);\n});\n```\n\n## Rule 7: Framework Integration\n\n**Framework-specific safe patterns:**\n\n```javascript\n// React: Safe HTML rendering\nfunction SafeComponent({ htmlContent }) {\n const clean = DOMPurify.sanitize(htmlContent, {\n ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p', 'br']\n });\n return ;\n}\n\n// Vue: Safe directive\nVue.directive('safe-html', {\n update: (el, binding) => {\n el.innerHTML = DOMPurify.sanitize(binding.value, {\n ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p', 'br']\n });\n }\n});\n```\n\n## Violation Detection Patterns\n\n**These patterns will trigger security violations:**\n\n```javascript\n// VIOLATION: Direct DOM manipulation\nelement.innerHTML = userInput;\neval(userData);\nsetTimeout(userData, 100);\nlocation.href = userUrl;\nelement.onclick = userHandler;\n\n// VIOLATION: Unescaped template literals\nconst html = `${userInput}
`;\n\n// VIOLATION: Missing validation\nwindow.addEventListener('message', (e) => processMessage(e.data));\n```\n\n## Mandatory Compliance Checks\n\n\nâś… **DOMPurify imported and used for HTML insertion**\nâś… **No innerHTML/outerHTML without sanitization**\nâś… **No eval(), new Function(), setTimeout/setInterval with strings**\nâś… **CSP implemented with script-src 'self'**\nâś… **Trusted Types policy implemented**\nâś… **URL validation before location assignments**\nâś… **Origin validation for postMessage**\n\n**VIOLATION CONSEQUENCES:** DOM-based XSS vulnerabilities allow arbitrary JavaScript execution, leading to account compromise, data theft, and malicious user actions.\n\n**TEST PAYLOADS:** Code must safely handle:\n- ``\n- `javascript:alert('XSS')`\n- `\">`\n- `'; eval('alert(1)'); //`"
},
{
"path": "sources/owasp/codeguard-0-dom-clobbering-prevention.md",
"content": "---\ndescription: DOM Clobbering Prevention Best Practices\nlanguages:\n- c\n- html\n- javascript\n- php\n- typescript\n- vlang\nalwaysApply: false\n---\n\n## DOM Clobbering Prevention Security Rule\n\n**RULE ENFORCEMENT:** This rule prevents DOM clobbering attacks where malicious HTML elements with `id` or `name` attributes override JavaScript variables and browser APIs, potentially leading to XSS and security bypasses.\n\n## Rule 1: HTML Sanitization Requirements\n\n**YOU MUST sanitize all user-provided HTML** using DOMPurify or Sanitizer API:\n\n```javascript\n// REQUIRED: DOMPurify configuration\nconst clean = DOMPurify.sanitize(userInput, {\n SANITIZE_DOM: true, // Protects built-in APIs\n SANITIZE_NAMED_PROPS: true, // MANDATORY: Protects custom variables \n FORBID_ATTR: ['id', 'name'] // REQUIRED: Remove clobbering attributes\n});\n\n// ALTERNATIVE: Sanitizer API\nconst sanitizer = new Sanitizer({\n blockAttributes: [{'name': 'id', elements: '*'}, {'name': 'name', elements: '*'}]\n});\nelement.setHTML(userInput, {sanitizer});\n```\n\n**YOU ARE PROHIBITED FROM:**\n* Using `innerHTML` with unsanitized user input\n* Allowing `id` or `name` attributes in user-generated content\n* Disabling `SANITIZE_NAMED_PROPS` in DOMPurify configuration\n\n## Rule 2: Content Security Policy Requirements\n\n**YOU MUST implement strict CSP** to prevent DOM clobbering exploitation:\n\n```http\nContent-Security-Policy: \n script-src 'self' 'nonce-{random}';\n object-src 'none';\n base-uri 'self';\n require-trusted-types-for 'script';\n```\n\n**YOU MUST use Trusted Types** for DOM manipulation:\n\n```javascript\nconst policy = trustedTypes.createPolicy('dompurify', {\n createHTML: (string) => DOMPurify.sanitize(string, {SANITIZE_NAMED_PROPS: true})\n});\nelement.innerHTML = policy.createHTML(userInput);\n```\n\n## Rule 3: Variable Declaration Requirements\n\n**YOU MUST use explicit variable declarations** to prevent global namespace pollution:\n\n```javascript\n\"use strict\"; // REQUIRED in all JavaScript files\nconst config = { isAdmin: false }; // REQUIRED: Explicit declarations\nlet userState = {}; // REQUIRED: Block-scoped variables\n\n// PROHIBITED: Creates vulnerable globals\nconfig = { isAdmin: false }; // WILL BE FLAGGED AS VIOLATION\n```\n\n**YOU ARE PROHIBITED FROM:**\n* Storing sensitive data on `window` or `document` objects\n* Using implicit global variables without declaration keywords\n* Accessing user input on the left side of assignment expressions\n\n## Rule 4: Object Validation Requirements\n\n**YOU MUST validate object types** before accessing potentially clobbered properties:\n\n```javascript\n// REQUIRED: Type validation before use\nfunction safePropertyAccess(obj, property) {\n if (obj && typeof obj === 'object' && !(obj instanceof Element)) {\n return obj[property];\n }\n throw new Error('Potential DOM clobbering detected');\n}\n\n// REQUIRED: Validate built-in APIs\nif (typeof document.getElementById === 'function') {\n const element = document.getElementById('myId');\n}\n```\n\n## Rule 5: Dynamic Attribute Restrictions\n\n**YOU MUST validate all dynamic HTML attributes:**\n\n```javascript\nfunction setElementAttribute(element, name, value) {\n const forbidden = ['id', 'name', 'onclick', 'onload', 'onerror'];\n if (forbidden.includes(name.toLowerCase())) {\n throw new Error(`Attribute ${name} is prohibited for security`);\n }\n element.setAttribute(name, DOMPurify.sanitize(value, {ALLOWED_TAGS: []}));\n}\n```\n\n**YOU ARE PROHIBITED FROM:**\n* Setting `id` or `name` attributes from user input\n* Using dynamic attribute assignment without validation\n* Bypassing sanitization for `data-` or `aria-` attributes\n\n## Rule 6: Framework Security Requirements\n\n**React/Vue applications MUST use sanitized HTML rendering:**\n\n```javascript\n// REACT: Required safe HTML component\nfunction SafeHtmlComponent({ userContent }) {\n const clean = DOMPurify.sanitize(userContent, {\n SANITIZE_NAMED_PROPS: true,\n FORBID_ATTR: ['id', 'name']\n });\n return ;\n}\n\n// VUE: Required directive\nVue.directive('safe-html', {\n update(el, binding) {\n el.innerHTML = DOMPurify.sanitize(binding.value, {\n SANITIZE_NAMED_PROPS: true,\n FORBID_ATTR: ['id', 'name']\n });\n }\n});\n```\n\n## Rule 7: Runtime Monitoring Requirements\n\n**YOU MUST implement DOM clobbering detection:**\n\n```javascript\n// REQUIRED: Runtime monitoring\nfunction detectClobbering() {\n ['config', 'api', 'user', 'admin'].forEach(global => {\n if (window[global] instanceof Element) {\n console.error(`SECURITY VIOLATION: DOM Clobbering detected on ${global}`);\n securityLogger.warn('DOM_CLOBBERING_DETECTED', { variable: global });\n }\n });\n}\nsetInterval(detectClobbering, 5000);\n```\n\n## Rule Violation Detection\n\n**The following patterns will trigger security violations:**\n\n```javascript\n// VIOLATION: Implicit global creation\nconfig = { sensitive: true };\n\n// VIOLATION: Storing sensitive data on window\nwindow.userRole = 'admin';\n\n// VIOLATION: Unvalidated innerHTML usage\nelement.innerHTML = userInput;\n\n// VIOLATION: Dynamic property access without validation\nobj[userControlledProperty] = value;\n\n// VIOLATION: Missing sanitization\ndocument.body.appendChild(htmlFromUser);\n```\n\n## Mandatory Compliance Checks\n\nThe following checks MUST be performed:\n\nâś… **DOMPurify imported and configured with `SANITIZE_NAMED_PROPS: true`**\nâś… **No direct `innerHTML` usage without sanitization**\nâś… **Strict mode enabled in all JavaScript files**\nâś… **CSP headers implemented with `script-src 'self'`**\nâś… **No `id` or `name` attributes in user content**\nâś… **Runtime clobbering detection implemented**\nâś… **Type validation before property access**\n\n**NON-COMPLIANCE CONSEQUENCES:** Code that violates these rules creates DOM clobbering vulnerabilities that can lead to XSS attacks and privilege escalation.\n\n**TEST PAYLOAD:** `` must be properly sanitized or blocked."
},
{
"path": "sources/owasp/codeguard-0-dotnet-security.md",
"content": "---\ndescription: DotNet Security Best Practices\nlanguages:\n- c\n- javascript\n- xml\nalwaysApply: false\n---\n\n## .NET Security Guidelines\n\nThis rule advises on critical .NET security practices to prevent common web vulnerabilities:\n\n- General Security Configuration\n - Keep .NET Framework, .NET Core, and all NuGet packages up-to-date.\n - Use Software Composition Analysis (SCA) tools in CI/CD pipelines.\n - Subscribe to .NET Core and ASP.NET Core security announcements on GitHub.\n\n- Access Control and Authorization\n - Use `[Authorize]` attributes at controller or method level for all externally facing endpoints.\n - Always validate user permissions server-side before resource access.\n - Check roles using `User.Identity.IsInRole` in code when needed.\n - Implement proper direct object reference validation to prevent IDOR attacks.\n\n- Authentication and Session Management\n - Use ASP.NET Core Identity with secure password policies and account lockout.\n - Set cookies with `HttpOnly = true` and `requireSSL = true` in production.\n - Reduce session timeout and disable sliding expiration for better security.\n - Throttle login, registration, and password reset methods against brute force attacks.\n\n- Cryptographic Security\n - Never write custom cryptographic functions; use .NET's proven implementations.\n - Use strong hashing algorithms: SHA512 for general hashing, PBKDF2 for passwords.\n - Use AES-GCM for encryption with proper key management.\n - Use Windows Data Protection API (DPAPI) for secure local storage.\n - Enforce TLS 1.2+ for all network communications.\n\n- Injection Prevention\n - Use parameterized SQL queries or Entity Framework exclusively.\n - Never concatenate user input into SQL commands or OS commands.\n - Use allowlist validation on all user input with methods like `IPAddress.TryParse`.\n - Escape LDAP special characters with backslash when needed.\n\n- Security Misconfiguration\n - Disable debug and tracing in production using web.config transforms.\n - Force HTTPS redirects using `app.UseHttpsRedirection()` or Global.asax.\n - Remove server version headers and implement secure HTTP headers.\n - Never use default passwords or credentials.\n\n- CSRF Protection\n - Use anti-forgery tokens with `@Html.AntiForgeryToken()` in forms.\n - Validate tokens with `[ValidateAntiForgeryToken]` on POST/PUT actions.\n - Set `ViewStateUserKey = Session.SessionID` for Web Forms CSRF protection.\n - Remove anti-forgery cookies on logout.\n\n- Secure Headers Configuration\n - Set `X-Frame-Options`, `X-Content-Type-Options`, `Content-Security-Policy` headers.\n - Configure HSTS with `Strict-Transport-Security` header.\n - Remove `X-Powered-By` and version disclosure headers.\n\n- Logging and Monitoring\n - Log authentication failures, access control violations with user context.\n - Use ILogger framework for centralized logging.\n - Never log sensitive data like passwords or tokens.\n - Include stack traces and error context in security logs.\n\n- Serialization Security\n - Avoid `BinaryFormatter` which is dangerous for untrusted data.\n - Use `System.Text.Json`, `XmlSerializer`, or `DataContractSerializer` safely.\n - Never deserialize untrusted data without validation.\n - Implement digital signature validation for serialized objects.\n\nCSRF Protection Example (from OWASP):\n\n```csharp\nprotected override OnInit(EventArgs e) {\n base.OnInit(e);\n ViewStateUserKey = Session.SessionID;\n}\n```\n\nSecure Headers Configuration (from OWASP):\n\n```xml\n\n \n \n \n \n \n \n \n \n \n \n\n```\n\nSummary: \nSecure .NET applications by implementing proper authorization controls, using secure authentication and session management, applying strong cryptography, preventing injection attacks, configuring security headers, implementing CSRF protection, maintaining secure configurations, logging security events properly, and handling serialization safely."
},
{
"path": "sources/owasp/codeguard-0-error-handling.md",
"content": "---\ndescription: Error Handling Security Best Practices\nlanguages:\n- c\n- java\n- javascript\n- python\n- typescript\n- xml\nalwaysApply: false\n---\n\n## Error Handling Security Guidelines\n\nThis rule advises on secure error handling practices to prevent information leakage and ensure proper logging:\n\n- General Error Handling Security\n - Implement global error handlers to catch all unhandled exceptions.\n - Return generic error messages without exposing stack traces, file paths, or version information.\n - Log detailed error information securely on the server side for investigation.\n - Use appropriate HTTP status codes: 4xx for client errors, 5xx for server errors.\n\n- Production Environment Configuration\n - Disable detailed error pages and debug information in production.\n - Set `customErrors mode=\"RemoteOnly\"` in web.config for ASP.NET applications.\n - Disable development exception pages in ASP.NET Core production environments.\n - Configure proper error page redirects to generic error handlers.\n\n- Secure Error Logging\n - Log exceptions with sufficient context (user ID, IP address, timestamp) for forensics.\n - Never log sensitive data like passwords, tokens, or personal information in error logs.\n - Use structured logging for better analysis and monitoring.\n - Implement log rotation and secure storage for error logs.\n\n- Error Response Security\n - Return consistent error response formats using standards like RFC 7807.\n - Add security headers to error responses to prevent XSS and information disclosure.\n - Ensure error response content is properly escaped to prevent injection attacks.\n - Remove server version headers and technology stack information from error responses.\n\nCode Examples (from OWASP):\n\nStandard Java Web Application:\n```xml\n\n\n java.lang.Exception\n /error.jsp\n\n```\n\n```java\n<%@ page language=\"java\" isErrorPage=\"true\" contentType=\"application/json; charset=UTF-8\"\n pageEncoding=\"UTF-8\"%>\n<%\nString errorMessage = exception.getMessage();\n//Log the exception via the content of the implicit variable named \"exception\"\n//...\n//We build a generic response with a JSON format because we are in a REST API app context\n//We also add an HTTP response header to indicate to the client app that the response is an error\nresponse.setHeader(\"X-ERROR\", \"true\");\n//Note that we're using an internal server error response\n//In some cases it may be prudent to return 4xx error codes, when we have misbehaving clients\nresponse.setStatus(500);\n%>\n{\"message\":\"An error occur, please retry\"}\n```\n\nSpring Boot Global Error Handler:\n```java\n\n@RestControllerAdvice\npublic class RestResponseEntityExceptionHandler extends ResponseEntityExceptionHandler {\n\n @ExceptionHandler(value = {Exception.class})\n public ProblemDetail handleGlobalError(RuntimeException exception, WebRequest request) {\n //Log the exception via the content of the parameter named \"exception\"\n //...\n //Note that we're using an internal server error response\n //In some cases it may be prudent to return 4xx error codes, if we have misbehaving clients\n //By specification, the content-type can be \"application/problem+json\" or \"application/problem+xml\"\n return ProblemDetail.forStatusAndDetail(HttpStatus.INTERNAL_SERVER_ERROR, \"An error occur, please retry\");\n }\n}\n```\n\nASP.NET Core Error Controller:\n```csharp\n[Route(\"api/[controller]\")]\n[ApiController]\n[AllowAnonymous]\npublic class ErrorController : ControllerBase\n{\n [HttpGet]\n [HttpPost]\n [HttpHead]\n [HttpDelete]\n [HttpPut]\n [HttpOptions]\n [HttpPatch]\n public JsonResult Handle()\n {\n //Get the exception that has implied the call to this controller\n Exception exception = HttpContext.Features.Get()?.Error;\n //Log the exception via the content of the variable named \"exception\" if it is not NULL\n //...\n //We build a generic response with a JSON format because we are in a REST API app context\n //We also add an HTTP response header to indicate to the client app that the response is an error\n var responseBody = new Dictionary{ {\n \"message\", \"An error occur, please retry\"\n } };\n JsonResult response = new JsonResult(responseBody);\n //Note that we're using an internal server error response\n //In some cases it may be prudent to return 4xx error codes, if we have misbehaving clients\n response.StatusCode = (int)HttpStatusCode.InternalServerError;\n Request.HttpContext.Response.Headers.Remove(\"X-ERROR\");\n Request.HttpContext.Response.Headers.Add(\"X-ERROR\", \"true\");\n return response;\n }\n}\n```\n\nASP.NET Web.config Security Configuration:\n```xml\n\n \n \n \n\n```\n\nSummary: \nImplement centralized error handling with generic user messages while logging detailed error information securely. Disable debug information in production and ensure error responses don't leak sensitive system details."
},
{
"path": "sources/owasp/codeguard-0-file-upload.md",
"content": "---\ndescription: File Upload Security Best Practices\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\nalwaysApply: false\n---\n\n## File Upload Security Guidelines\n\nThis rule advises on secure file upload practices to prevent malicious file attacks and protect system integrity:\n\n- Extension Validation\n - List allowed extensions only for business-critical functionality.\n - Ensure input validation is applied before validating extensions.\n - Avoid double extensions (e.g., `.jpg.php`) and null byte injection (e.g., `.php%00.jpg`).\n - Use allowlist approach rather than denylist for file extensions.\n - Validate extensions after decoding filename to prevent bypass attempts.\n\n- Content Type and File Signature Validation\n - Never trust client-supplied Content-Type headers as they can be spoofed.\n - Validate file signatures (magic numbers) in conjunction with Content-Type checking.\n - Implement allowlist approach for MIME types as a quick protection layer.\n - Use file signature validation but not as a standalone security measure.\n\n- Filename Security\n - Generate random filenames (UUID/GUID) instead of using user-supplied names.\n - If user filenames required, implement maximum length limits.\n - Restrict characters to alphanumeric, hyphens, spaces, and periods only.\n - Prevent leading periods (hidden files) and sequential periods (directory traversal).\n - Avoid leading hyphens or spaces for safer shell script processing.\n\n- File Content Validation\n - For images, apply image rewriting techniques to destroy malicious content.\n - For Microsoft documents, use Apache POI for validation.\n - Avoid ZIP files due to numerous attack vectors.\n - Implement manual file review in sandboxed environments when resources allow.\n - Integrate antivirus scanning and Content Disarm & Reconstruct (CDR) for applicable file types.\n\n- Storage Security\n - Store files on different servers for complete segregation when possible.\n - Store files outside webroot with administrative access only.\n - If storing in webroot, set write-only permissions with proper access controls.\n - Use application handlers that map IDs to filenames for public access.\n - Consider database storage for specific use cases with DBA expertise.\n\n- Access Control and Authentication\n - Require user authentication before allowing file uploads.\n - Implement proper authorization levels for file access and modification.\n - Set filesystem permissions on principle of least privilege.\n - Scan files before execution if execution permission is required.\n\n- Upload and Download Limits\n - Set proper file size limits for upload protection.\n - Consider post-decompression size limits for compressed files.\n - Implement request limits for download services to prevent DoS attacks.\n - Use secure methods to calculate ZIP file sizes safely.\n\n- Additional Security Measures\n - Protect file upload endpoints from CSRF attacks.\n - Keep all file processing libraries securely configured and updated.\n - Implement logging and monitoring for upload activities.\n - Provide user reporting mechanisms for illegal content.\n - Use secure extraction methods for compressed files.\n\nSummary: \nImplement defense-in-depth for file uploads through multi-layered validation, secure storage practices, proper access controls, and comprehensive monitoring. Never rely on single validation methods and always generate safe filenames to prevent attacks."
},
{
"path": "sources/owasp/codeguard-0-forgot-password.md",
"content": "---\ndescription: Forgot Password Security Best Practices\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\nalwaysApply: false\n---\n\n## Forgot Password Security Guidelines\n\nThis rule advises on secure password reset implementation to prevent user enumeration, token abuse, and unauthorized access:\n\n- Password Reset Request Security\n - Return consistent messages for both existent and non-existent accounts to prevent user enumeration.\n - Ensure consistent response times by using asynchronous processing or identical code paths.\n - Implement rate limiting per account and IP address to prevent flooding attacks.\n - Apply input validation and SQL injection prevention to reset request forms.\n - Use CSRF tokens to protect password reset forms and endpoints.\n\n- Token Generation and Storage\n - Generate tokens using cryptographically secure random number generators.\n - Make tokens sufficiently long to protect against brute-force attacks (minimum 32 bytes).\n - Store password reset tokens securely using hashing (same practices as password storage).\n - Link tokens to individual users in the database with expiration times.\n - Make tokens single-use and invalidate immediately after successful use.\n\n- Password Reset Process Security\n - Require users to confirm new passwords by entering twice.\n - Enforce consistent password policy throughout the application.\n - Store new passwords following secure password storage practices.\n - Send confirmation emails without including the actual password.\n - Never automatically log users in after password reset.\n - Invalidate all existing user sessions after successful password reset.\n\n- URL Token Implementation\n - Generate secure tokens and attach to URL query strings for email delivery.\n - Use hardcoded or validated trusted domains for reset URLs (avoid Host header injection).\n - Enforce HTTPS for all password reset URLs.\n - Add referrer policy with 'noreferrer' value to prevent referrer leakage.\n - Implement rate limiting to prevent token brute-forcing attempts.\n\n- PIN Implementation\n - Generate PINs between 6-12 digits using cryptographically secure methods.\n - Create limited sessions from PINs that only permit password reset operations.\n - Format PINs with spaces for better user readability.\n - Apply same security practices as tokens (single-use, expiration, secure storage).\n\n- Security Questions Integration\n - Use security questions only as additional layer, never as sole mechanism.\n - Follow secure question selection practices from OWASP guidance.\n - Validate security question answers using secure comparison methods.\n\n- Logging and Monitoring (Code-Level)\n - Log password reset attempts with user context but never log tokens or passwords.\n - Implement structured logging for security monitoring integration.\n - Include sufficient context for security analysis (IP, user agent, timestamp).\n - Never log sensitive information in application logs.\n\n- Account Lockout Prevention\n - Never lock accounts in response to password reset requests.\n - Implement alternative abuse prevention through rate limiting and monitoring.\n - Separate password reset abuse protection from authentication lockout mechanisms.\n\nSummary: \nImplement secure password reset functionality through consistent response handling, cryptographically secure token generation and storage, CSRF protection, proper session management, and comprehensive logging while preventing user enumeration and account lockout attacks."
},
{
"path": "sources/owasp/codeguard-0-graphql.md",
"content": "---\ndescription: GraphQL Security Best Practices\nlanguages:\n- javascript\n- typescript\nalwaysApply: false\n---\n\n## GraphQL Security Guidelines\n\nThis rule advises on secure GraphQL API development to prevent injection, DoS, unauthorized access, and information leakage:\n\n- Input Validation and Injection Prevention\n - Use specific GraphQL data types (scalars, enums) for all input validation.\n - Define custom GraphQL validators for complex validations and use custom scalars.\n - Define schemas for mutation inputs with strict validation rules.\n - Use allowlist approach for character validation (avoid denylists).\n - Apply parameterized statements and safe APIs for database queries in resolvers.\n - Use ORMs/ODMs properly to avoid ORM injection vulnerabilities.\n - Gracefully reject invalid input without revealing internal API details.\n\n- DoS Prevention and Query Limiting\n - Implement query depth limiting using libraries like graphql-depth-limit (JavaScript) or MaxQueryDepthInstrumentation (Java).\n - Add query complexity analysis using graphql-cost-analysis or MaxQueryComplexityInstrumentation.\n - Enforce query amount limiting with libraries like graphql-input-number.\n - Implement pagination to limit data returned in single responses.\n - Add query timeouts at application level using custom instrumentation.\n - Apply rate limiting per IP or user to prevent basic DoS attacks.\n - Use server-side batching and caching (like Facebook's DataLoader) for efficiency.\n\n- Access Control and Authorization\n - Validate requester authorization for all data viewing and mutation operations.\n - Implement proper object-level authorization to prevent IDOR/BOLA vulnerabilities.\n - Enforce authorization checks on both edges and nodes in GraphQL schema.\n - Use Interfaces and Unions to return different object properties based on permissions.\n - Add access control validation in Query and Mutation resolvers with RBAC middleware.\n - Check for unintended node/nodes fields that allow direct object access by ID.\n - Implement field-level access controls for sensitive data.\n\n- Batching Attack Prevention\n - Limit the number of queries that can be batched and run simultaneously.\n - Add object request rate limiting at code level to track instance requests.\n - Prevent batching for sensitive objects (usernames, passwords, tokens, OTPs).\n - Implement custom solutions to disable batching for critical operations.\n - Monitor and log batching attempts for security analysis.\n\n- Secure Configuration Management\n - Disable GraphQL introspection in production environments using NoIntrospectionGraphqlFieldVisibility (Java) or validation rules (JavaScript).\n - Disable GraphiQL and similar exploration tools in production.\n - Configure error masking to prevent stack traces and debug information exposure.\n - Set NODE_ENV to 'production' or use debug: false in Apollo Server configuration.\n - Disable field suggestion hints when introspection is disabled.\n\n- Authentication and Session Management\n - Require authentication for all GraphQL endpoints (unless explicitly public).\n - Implement proper session management with secure token validation.\n - Use JWT or session-based authentication with proper validation in resolvers.\n - Apply CSRF protection for GraphQL mutations when using cookie-based authentication.\n - Validate authentication state before processing any queries or mutations.\n\nCode Examples (from OWASP):\n\nDisable Introspection - Java:\n```java\nGraphQLSchema schema = GraphQLSchema.newSchema()\n .query(StarWarsSchema.queryType)\n .fieldVisibility( NoIntrospectionGraphqlFieldVisibility.NO_INTROSPECTION_FIELD_VISIBILITY )\n .build();\n```\n\nDisable Introspection & GraphiQL - JavaScript:\n```javascript\napp.use('/graphql', graphqlHTTP({\n schema: MySessionAwareGraphQLSchema,\n+ validationRules: [NoIntrospection]\n graphiql: process.env.NODE_ENV === 'development',\n}));\n```\n\nQuery Depth Example:\n```javascript\nquery evil { # Depth: 0\n album(id: 42) { # Depth: 1\n songs { # Depth: 2\n album { # Depth: 3\n songs { # Depth: 4\n album {id: N} # Depth: N\n }\n }\n }\n }\n}\n```\n\nExcessive Amount Request Example:\n```javascript\nquery {\n author(id: \"abc\") {\n posts(first: 99999999) {\n title\n }\n }\n}\n```\n\nBatching Attack Example:\n```javascript\n[\n {\n query: < query 0 >,\n variables: < variables for query 0 >,\n },\n {\n query: < query 1 >,\n variables: < variables for query 1 >,\n },\n {\n query: < query n >\n variables: < variables for query n >,\n }\n]\n```\n\nSummary: \nSecure GraphQL APIs through comprehensive input validation, query limiting, proper access controls, batching attack prevention, secure configuration management, and robust authentication mechanisms while preventing common attack vectors like injection, DoS, and unauthorized data access."
},
{
"path": "sources/owasp/codeguard-0-html5-security.md",
"content": "---\ndescription: HTML5 Security Best Practices\nlanguages:\n- c\n- go\n- html\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\n- xml\nalwaysApply: false\n---\n\n## HTML5 Security Guidelines\n\nThis rule advises on secure HTML5 development practices to prevent vulnerabilities in modern web applications:\n\n- Web Messaging Security\n - Always specify exact target origin in postMessage calls, never use \"*\" wildcard.\n - Verify event.origin strictly against trusted full domain names in message handlers.\n - Avoid partial domain matching that could allow subdomain takeover attacks.\n - Validate and sanitize all data received through postMessage before processing.\n - Never use eval() or Function() constructor on message data.\n - Use textContent instead of innerHTML when setting received message content.\n - Treat all cross-origin message data as untrusted input requiring validation.\n\n- Cross-Origin Resource Sharing (CORS) Security\n - Restrict Access-Control-Allow-Origin to specific trusted origins, avoid \"*\" wildcard.\n - Validate URLs passed to XMLHttpRequest.open to prevent open redirects.\n - Implement proper CSRF protection even when using CORS (CORS doesn't prevent CSRF).\n - Reject mixed content requests (HTTP requests from HTTPS origins).\n - Don't rely solely on Origin header for access control as it can be spoofed outside browsers.\n - Use preflight requests for non-simple requests and validate Access-Control headers.\n\n- WebSocket Security\n - Use only secure wss:// protocol, never unencrypted ws:// in production.\n - Implement application-level authentication and authorization for WebSocket connections.\n - Verify Origin header against allowlist during WebSocket handshake.\n - Validate and parse all WebSocket messages safely using JSON.parse() with error handling.\n - Implement connection limits and message size restrictions to prevent DoS attacks.\n - Use JWT or similar tokens for WebSocket authentication with proper validation.\n - Implement token invalidation and denylist mechanisms for revoked access.\n\n- Client-Side Storage Security\n - Never store sensitive data (passwords, tokens, API keys, PII) in localStorage or sessionStorage.\n - Use sessionStorage instead of localStorage when persistence across browser sessions is not required.\n - Validate and sanitize all data retrieved from client-side storage before use.\n - Implement data encryption for sensitive information stored client-side when absolutely necessary.\n - Avoid hosting multiple applications on same origin to prevent storage access conflicts.\n\n- DOM Manipulation and Link Security\n - Add rel=\"noopener noreferrer\" attribute to all external links with target=\"_blank\".\n - Set window.opener = null when using window.open() for external URLs.\n - Use iframe sandbox attribute with minimal permissions for untrusted content.\n - Implement X-Frame-Options header alongside iframe sandbox for defense-in-depth.\n - Avoid innerHTML with user-supplied content; use textContent, createElement, or trusted templating.\n - When innerHTML must be used, sanitize content with DOMPurify or similar libraries.\n\n- Input Field Security and CSRF Protection\n - Use autocomplete=\"off\" on sensitive input fields (passwords, credit cards, SSN).\n - Add spellcheck=\"false\", autocorrect=\"off\", autocapitalize=\"off\" on credential inputs.\n - Implement CSRF tokens on all state-changing forms and AJAX requests.\n - Use secure cookie attributes: HttpOnly, Secure, SameSite=Strict for session cookies.\n - Validate CSRF tokens on server-side for all POST, PUT, DELETE requests.\n\n- Secure Cookie Configuration\n - Set HttpOnly flag on session cookies to prevent JavaScript access.\n - Use Secure flag to ensure cookies are only sent over HTTPS connections.\n - Implement SameSite=Strict or SameSite=Lax to prevent CSRF attacks.\n - Use __Secure- or __Host- cookie prefixes for additional security.\n - Set appropriate cookie expiration and path restrictions.\n\n- Web Workers and Service Workers Security\n - Validate all messages sent to and received from Web Workers.\n - Never create Web Workers from user-supplied URLs or content.\n - Implement proper error handling and timeout mechanisms for Worker communications.\n - Use Content Security Policy to restrict Worker script sources.\n - Validate Service Worker registration and update mechanisms.\n\n- Geolocation and Device API Security\n - Require explicit user permission before accessing Geolocation API.\n - Validate geolocation data before sending to servers.\n - Implement proper error handling for geolocation failures.\n - Use HTTPS when transmitting location data to prevent interception.\n\n- Offline Application Security\n - Require user consent before caching application data offline.\n - Validate integrity of cached resources to prevent cache poisoning.\n - Use HTTPS for all manifest files and cached resources.\n - Implement proper cache invalidation mechanisms for security updates.\n\nSummary: \nImplement comprehensive HTML5 security controls through proper origin validation, secure storage practices, CSRF protection, secure cookie configuration, safe DOM manipulation, and robust authentication mechanisms to prevent XSS, CSRF, clickjacking, and data leakage vulnerabilities."
},
{
"path": "sources/owasp/codeguard-0-http-headers.md",
"content": "---\ndescription: HTTP Security Headers Best Practices\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\n- xml\nalwaysApply: false\n---\n\n## HTTP Security Headers Guidelines\n\nThis rule enforces secure configuration of HTTP response headers to protect against common web vulnerabilities including XSS, Clickjacking, Information Disclosure, and MIME-type attacks.\n\n### Required Security Headers\n\n1. Content Security Policy (CSP)\n - Must include default-src directive\n - Must include script-src directive with appropriate restrictions\n - Must include frame-ancestors directive for clickjacking protection\n - Example: `Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; frame-ancestors 'none'`\n\n2. Cookie Security\n - All session/sensitive cookies must have Secure flag\n - All session/sensitive cookies must have HttpOnly flag\n - All cookies must have SameSite attribute (Strict or Lax)\n - Example: `Set-Cookie: session=123; Secure; HttpOnly; SameSite=Strict`\n\n3. Cross-Origin Isolation\n - Must set Cross-Origin-Embedder-Policy (COEP)\n - Must set Cross-Origin-Resource-Policy (CORP)\n - Must set Cross-Origin-Opener-Policy (COOP)\n - Examples:\n ```\n Cross-Origin-Embedder-Policy: require-corp\n Cross-Origin-Resource-Policy: same-origin\n Cross-Origin-Opener-Policy: same-origin\n ```\n\n4. Transport Security\n - Must set Strict-Transport-Security (HSTS)\n - Must include appropriate max-age (minimum 1 year)\n - Example: `Strict-Transport-Security: max-age=31536000; includeSubDomains`\n\n5. Cache Control\n - Must set appropriate Cache-Control for sensitive data\n - Example: `Cache-Control: no-store, max-age=0`\n\n6. Content Type Protection\n - Must set X-Content-Type-Options\n - Example: `X-Content-Type-Options: nosniff`\n\n### Prohibited Headers\n\nThe following headers must not be present or must be removed:\n- X-Powered-By\n- Server (or must contain non-revealing value)\n- X-AspNet-Version\n- X-AspNetMvc-Version\n\n### Required Header Combinations\n\nCertain security features require multiple headers to work effectively:\n\n1. Clickjacking Protection:\n - Must use CSP frame-ancestors OR\n - Must use X-Frame-Options: DENY\n\n2. XSS Protection:\n - Must use CSP with appropriate script-src\n - Must not rely solely on X-XSS-Protection\n\n3. CORS Security:\n - Must not use Access-Control-Allow-Origin: *\n - Must explicitly list allowed origins\n\n### Implementation Examples\n\nPHP:\n```php\nheader(\"X-Frame-Options: DENY\");\n```\n\nApache (.htaccess):\n```apache\n\nHeader always set X-Frame-Options \"DENY\"\n\n```\n\nIIS (Web.config):\n```xml\n\n...\n \n \n \n \n \n...\n\n```\n\nHAProxy:\n```\nhttp-response set-header X-Frame-Options DENY\n```\n\nNginx:\n```nginx\nadd_header \"X-Frame-Options\" \"DENY\" always;\n```\n\nExpress.js:\n```javascript\nconst helmet = require('helmet');\nconst app = express();\n// Sets \"X-Frame-Options: SAMEORIGIN\"\napp.use(\n helmet.frameguard({\n action: \"sameorigin\",\n })\n);\n```\n\n### Testing Tools\n\nMozilla Observatory is an online tool which helps you to check your website's header status.\n\nSmartScanner has a dedicated test profile for testing security of HTTP headers. Online tools usually test the homepage of the given address. But SmartScanner scans the whole website, ensuring all web pages have the right HTTP Headers in place."
},
{
"path": "sources/owasp/codeguard-0-http-strict-transport-security.md",
"content": "---\ndescription: HTTP Strict Transport Security Best Practices\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\nalwaysApply: false\n---\n\n## HTTP Strict Transport Security Guidelines\n\nThis rule enforces secure configuration of HTTP Strict Transport Security (HSTS) headers to protect users by ensuring all communications occur over HTTPS.\n\n### Introduction\n\nHTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified by a web application through a special response header. Once a supported browser receives this header, it prevents any communications from being sent over HTTP to the specified domain and instead sends all communications over HTTPS. It also prevents HTTPS click through prompts on browsers.\n\nCritical Requirement: The Strict-Transport-Security header is only honored over HTTPS connections and is completely ignored when sent over HTTP, per RFC 6797.\n\n### Threats Addressed\n\nHSTS protects against:\n- Man-in-the-middle attacks when users bookmark or manually type `http://example.com`\n- Web applications inadvertently containing HTTP links or serving content over HTTP\n- Man-in-the-middle attackers using invalid certificates (HSTS prevents users from accepting bad certificates)\n\n### Required Configuration\n\n1. Basic HSTS Header (testing phase):\n ```\n Strict-Transport-Security: max-age=86400; includeSubDomains\n ```\n\n2. Production HSTS Header (1 year minimum):\n ```\n Strict-Transport-Security: max-age=31536000; includeSubDomains\n ```\n\n3. Preload-Ready HSTS Header:\n ```\n Strict-Transport-Security: max-age=31536000; includeSubDomains; preload\n ```\n\n### Phased Rollout Requirements\n\n1. Phase 1 - Testing (recommended first step):\n - Use short max-age (600-86400 seconds) for initial testing\n - Monitor for any HTTP content or functionality issues\n\n2. Phase 2 - Production:\n - Increase max-age to minimum 1 year (31536000 seconds)\n - Add `includeSubDomains` only if all subdomains support HTTPS\n\n3. Phase 3 - Preload (optional):\n - Add `preload` directive only after thorough testing\n - Submit domain to HSTS preload list at hstspreload.org\n - Warning: Preload is effectively permanent and affects all subdomains\n\n### Implementation Examples\n\nSimple example using 1 year max-age (dangerous without includeSubDomains):\n```\nStrict-Transport-Security: max-age=31536000\n```\n\nSecure example with subdomain protection:\n```\nStrict-Transport-Security: max-age=31536000; includeSubDomains\n```\n\nShort max-age for initial rollout testing:\n```\nStrict-Transport-Security: max-age=86400; includeSubDomains\n```\n\n### Monitoring and Validation\n\nRequired post-deployment actions:\n- Verify HSTS header presence in all HTTPS responses\n- Monitor browser console for mixed content warnings\n- Audit all internal links and redirects for HTTP references\n- Test subdomain HTTPS availability before enabling includeSubDomains\n- Use tools like Mozilla Observatory or Security Headers to validate configuration\n\n### Browser Support\n\nHSTS is supported by all modern browsers. The only notable exception is Opera Mini."
},
{
"path": "sources/owasp/codeguard-0-injection-prevention.md",
"content": "---\ndescription: Injection Prevention Best Practices\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- powershell\n- python\n- ruby\n- shell\n- sql\n- typescript\nalwaysApply: false\n---\n\n## Injection Prevention Guidelines\n\nThis rule provides clear, actionable guidance for preventing injection flaws across multiple languages and injection types. Injection flaws occur when untrusted data is sent to an interpreter as part of a command or query.\n\n### Introduction\n\nInjection attacks, especially SQL Injection, are unfortunately very common. Injection flaws occur when an application sends untrusted data to an interpreter. Injection flaws are very prevalent, particularly in legacy code, often found in SQL queries, LDAP queries, XPath queries, OS commands, program arguments, etc.\n\n### SQL Injection Prevention\n\nDefense Option 1: Prepared Statements (with Parameterized Queries)\n\nSafe Java Prepared Statement Example:\n```java\n// This should REALLY be validated too\nString custname = request.getParameter(\"customerName\"); \nString query = \"SELECT account_balance FROM user_data WHERE user_name = ?\";\nPreparedStatement pstmt = connection.prepareStatement( query );\npstmt.setString( 1, custname); \nResultSet results = pstmt.executeQuery( );\n```\n\nDefense Option 2: Stored Procedures\n\nSafe Java Stored Procedure Example:\n```java\n// This should REALLY be validated\nString custname = request.getParameter(\"customerName\");\ntry {\n CallableStatement cs = connection.prepareCall(\"{call sp_getAccountBalance(?)}\");\n cs.setString(1, custname);\n ResultSet results = cs.executeQuery();\n // Result set handling...\n} catch (SQLException se) {\n // Logging and error handling...\n}\n```\n\nDefense Option 3: Allow-List Input Validation\n\nDefense Option 4: Escaping All User-Supplied Input\n\n### LDAP Injection Prevention\n\nEscape all variables using the right LDAP encoding function\n\nSafe Java for LDAP escaping Example:\n```java\npublic String escapeDN (String name) {\n //From RFC 2253 and the / character for JNDI\n final char[] META_CHARS = {'+', '\"', '<', '>', ';', '/'};\n String escapedStr = new String(name);\n //Backslash is both a Java and an LDAP escape character,\n //so escape it first\n escapedStr = escapedStr.replaceAll(\"\\\\\\\\\\\\\\\\\",\"\\\\\\\\\\\\\\\\\");\n //Positional characters - see RFC 2253\n escapedStr = escapedStr.replaceAll(\"\\^#\",\"\\\\\\\\\\\\\\\\#\");\n escapedStr = escapedStr.replaceAll(\"\\^ | $\",\"\\\\\\\\\\\\\\\\ \");\n for (int i=0 ; i < META_CHARS.length ; i++) {\n escapedStr = escapedStr.replaceAll(\"\\\\\\\\\" +\n META_CHARS[i],\"\\\\\\\\\\\\\\\\\" + META_CHARS[i]);\n }\n return escapedStr;\n}\n```\n\n```java\npublic String escapeSearchFilter (String filter) {\n //From RFC 2254\n String escapedStr = new String(filter);\n escapedStr = escapedStr.replaceAll(\"\\\\\\\\\\\\\\\\\",\"\\\\\\\\\\\\\\\\5c\");\n escapedStr = escapedStr.replaceAll(\"\\\\\\\\\\*\",\"\\\\\\\\\\\\\\\\2a\");\n escapedStr = escapedStr.replaceAll(\"\\\\\\\\(\",\"\\\\\\\\\\\\\\\\28\");\n escapedStr = escapedStr.replaceAll(\"\\\\\\\\)\",\"\\\\\\\\\\\\\\\\29\");\n escapedStr = escapedStr.replaceAll(\"\\\\\\\\\" +\n Character.toString('\\u0000'), \"\\\\\\\\\\\\\\\\00\");\n return escapedStr;\n}\n```\n\n### Operating System Commands\n\nIf it is considered unavoidable the call to a system command incorporated with user-supplied input, the following two layers of defense should be used:\n\n1. Parameterization - If available, use structured mechanisms that automatically enforce the separation between data and command\n2. Input validation - the values for commands and the relevant arguments should be both validated:\n - Commands must be validated against a list of allowed commands\n - Arguments should be validated using positive or allowlist input validation\n - Allow-list Regular Expression - explicitly define a list of good characters allowed and maximum length. Ensure that metacharacters like `& | ; $ > < \\` \\ !` and whitespaces are not part of the Regular Expression\n\nExample regular expression: `^[a-z0-9]{3,10}$`\n\nIncorrect Usage:\n```java\nProcessBuilder b = new ProcessBuilder(\"C:\\DoStuff.exe -arg1 -arg2\");\n```\n\nCorrect Usage:\n```java\nProcessBuilder pb = new ProcessBuilder(\"TrustedCmd\", \"TrustedArg1\", \"TrustedArg2\");\nMap env = pb.environment();\npb.directory(new File(\"TrustedDir\"));\nProcess p = pb.start();\n```\n\n### Injection Prevention Rules\n\nRule #1 (Perform proper input validation)\n- Perform proper input validation. Positive or allowlist input validation with appropriate canonicalization is recommended, but is not a complete defense as many applications require special characters in their input.\n\nRule #2 (Use a safe API)\n- The preferred option is to use a safe API which avoids the use of the interpreter entirely or provides a parameterized interface. Be careful of APIs, such as stored procedures, that are parameterized, but can still introduce injection under the hood.\n\nRule #3 (Contextually escape user data)\n- If a parameterized API is not available, you should carefully escape special characters using the specific escape syntax for that interpreter."
},
{
"path": "sources/owasp/codeguard-0-input-validation.md",
"content": "---\ndescription: Input Validation Security Best Practices\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- sql\n- typescript\n- xml\nalwaysApply: false\n---\n\n## Input Validation Security Guidelines\n\nThis rule provides clear, actionable guidance for implementing robust input validation security functionality in applications.\n\n### Introduction\n\nInput validation ensures only properly formed data enters the workflow, preventing malformed data from persisting in the database and triggering malfunction of downstream components. Input validation should happen as early as possible in the data flow.\n\nData from all potentially untrusted sources should be subject to input validation, including Internet-facing web clients and backend feeds from suppliers, partners, vendors or regulators.\n\nInput Validation should not be used as the primary method of preventing XSS, SQL Injection and other attacks but can significantly contribute to reducing their impact if implemented properly.\n\n### Input Validation Strategies\n\n- Syntactic validation: enforce correct syntax of structured fields (e.g. SSN, date, currency symbol)\n- Semantic validation: enforce correctness of values in specific business context (e.g. start date before end date, price within expected range)\n\n### Implementing Input Validation\n\n- Data type validators available in web application frameworks (Django Validators, Apache Commons Validators)\n- Validation against JSON Schema and XML Schema (XSD)\n- Type conversion with strict exception handling (Integer.parseInt() in Java, int() in Python)\n- Range checks for numerical parameters and length checks for strings\n- Array of allowed values for small sets of string parameters\n- Regular expressions covering the whole input string (^...$) avoiding \"any character\" wildcards\n\n### Allowlist vs Denylist\n\nAllowlist validation defines exactly what IS authorized; everything else is not authorized. For structured data (dates, SSNs, zip codes, emails), define strong validation patterns using regular expressions. For fixed options (dropdowns, radio buttons), input must match exactly one offered value.\n\n### Validating Free-form Unicode Text\n\n- Normalization: Ensure canonical encoding across all text\n- Character category allowlisting: Use Unicode categories like \"decimal digits\" or \"letters\"\n- Individual character allowlisting: Allow specific characters like apostrophe for names\n\n### Regular Expressions (Regex)\n\nBe aware of RegEx Denial of Service (ReDoS) attacks. Input validation should:\n- Be applied to all input data\n- Define allowed character sets\n- Define minimum and maximum length (e.g. {1,25})\n\n### Allow List Regular Expression Examples\n\nU.S. Zip Code: `^\\d{5}(-\\d{4})?$`\n\nJava Example:\n```java\nprivate static final Pattern zipPattern = Pattern.compile(\"^\\d{5}(-\\d{4})?$\");\n\npublic void doPost(HttpServletRequest request, HttpServletResponse response) {\n try {\n String zipCode = request.getParameter(\"zip\");\n if (!zipPattern.matcher(zipCode).matches()) {\n throw new YourValidationException(\"Improper zipcode format.\");\n }\n } catch(YourValidationException e) {\n response.sendError(response.SC_BAD_REQUEST, e.getMessage());\n }\n}\n```\n\n### Client-side vs Server-side Validation\n\nInput validation must be implemented on the server-side before data processing, as client-side validation can be circumvented by attackers.\n\n### File Upload Validation\n\nUpload Verification:\n- Validate filename uses expected extension type\n- Enforce maximum file size limits\n- Check ZIP files before extraction (target path, compression level, estimated size)\n\nUpload Storage:\n- Use server-generated random filenames\n- Analyze uploaded files for malicious content\n- Server defines file paths, not client\n\nBeware of dangerous file types:\n- crossdomain.xml / clientaccesspolicy.xml\n- .htaccess and .htpasswd\n- Web executable scripts: aspx, asp, css, swf, jsp, js, php, cgi\n\nImage Upload:\n- Use image rewriting libraries to verify and strip content\n- Set extension based on detected content type\n- Ensure content type is within defined image types\n\n### Email Address Validation\n\nSyntactic Validation:\n- Contains two parts separated by @\n- No dangerous characters (backticks, quotes, null bytes)\n- Domain contains only letters, numbers, hyphens, periods\n- Length limits: local part ≤ 63 chars, total ≤ 254 chars\n\nSemantic Validation:\n- Send verification email with secure token\n- Token requirements: ≥32 chars, cryptographically random, single-use, time-limited"
},
{
"path": "sources/owasp/codeguard-0-insecure-direct-object-reference-prevention.md",
"content": "---\ndescription: Insecure Direct Object Reference Prevention\nlanguages:\n- c\n- go\n- java\n- javascript\n- kotlin\n- php\n- python\n- ruby\n- swift\n- typescript\nalwaysApply: false\n---\n\n## Insecure Direct Object Reference Prevention Guidelines\n\nThis rule provides actionable guidance for preventing IDOR vulnerabilities by implementing proper access control checks around direct object references.\n\n### Introduction\n\nInsecure Direct Object Reference (IDOR) is a vulnerability that arises when attackers can access or modify objects by manipulating identifiers used in a web application's URLs or parameters. It occurs due to missing access control checks, which fail to verify whether a user should be allowed to access specific data.\n\n### Examples\n\nFor instance, when a user accesses their profile, the application might generate a URL like this:\n\n```\nhttps://example.org/users/123\n```\n\nThe 123 in the URL is a direct reference to the user's record in the database, often represented by the primary key. If an attacker changes this number to 124 and gains access to another user's information, the application is vulnerable to Insecure Direct Object Reference.\n\nIn some cases, the identifier may not be in the URL, but rather in the POST body:\n\n```html\n\n```\n\nIn this example, attackers can manipulate the \"user_id\" field to modify profiles of other users without authorization.\n\n### Identifier Complexity\n\nIn some cases, using more complex identifiers like GUIDs can make it practically impossible for attackers to guess valid values. However, even with complex identifiers, access control checks are essential. If attackers obtain URLs for unauthorized objects, the application should still block their access attempts.\n\n### Mitigation\n\nTo mitigate IDOR, implement access control checks for each object that users try to access. Web frameworks often provide ways to facilitate this. Additionally, use complex identifiers as a defense-in-depth measure, but remember that access control is crucial even with these identifiers.\n\nAvoid exposing identifiers in URLs and POST bodies if possible. Instead, determine the currently authenticated user from session information. When using multi-step flows, pass identifiers in the session to prevent tampering.\n\nWhen looking up objects based on primary keys, use datasets that users have access to. For example, in Ruby on Rails:\n\n```ruby\n// vulnerable, searches all projects\n@project = Project.find(params[:id])\n// secure, searches projects related to the current user\n@project = @current_user.projects.find(params[:id])\n```\n\nVerify the user's permission every time an access attempt is made. Implement this structurally using the recommended approach for your web framework.\n\nAs an additional defense-in-depth measure, replace enumerable numeric identifiers with more complex, random identifiers. You can achieve this by adding a column with random strings in the database table and using those strings in the URLs instead of numeric primary keys. Another option is to use UUIDs or other long random values as primary keys. Avoid encrypting identifiers as it can be challenging to do so securely."
},
{
"path": "sources/owasp/codeguard-0-jaas.md",
"content": "---\ndescription: JAAS Security Best Practices\nlanguages:\n- c\n- java\n- xml\nalwaysApply: false\n---\n\n## Introduction - What is JAAS authentication\n\nThe process of verifying the identity of a user or another system is authentication.\n\nJAAS, as an authentication framework manages the authenticated user's identity and credentials from login to logout.\n\nThe JAAS authentication lifecycle:\n\n1. Create `LoginContext`.\n2. Read the configuration file for one or more `LoginModules` to initialize.\n3. Call `LoginContext.initialize()` for each LoginModule to initialize.\n4. Call `LoginContext.login()` for each LoginModule.\n5. If login successful then call `LoginContext.commit()` else call `LoginContext.abort()`\n\n## Configuration file\n\nThe JAAS configuration file contains a `LoginModule` stanza for each `LoginModule` available for logging on to the application.\n\nA stanza from a JAAS configuration file:\n\n```text\nBranches\n{\n USNavy.AppLoginModule required\n debug=true\n succeeded=true;\n}\n```\n\nNote the placement of the semicolons, terminating both `LoginModule` entries and stanzas.\n\nThe word required indicates the `LoginContext`'s `login()` method must be successful when logging in the user. The `LoginModule`-specific values `debug` and `succeeded` are passed to the `LoginModule`.\n\nThey are defined by the `LoginModule` and their usage is managed inside the `LoginModule`. Note, Options are Configured using key-value pairing such as `debug=\"true\"` and the key and value should be separated by a `=` sign.\n\n## Main.java (The client)\n\n- Execution syntax:\n\n```text\nJava –Djava.security.auth.login.config==packageName/packageName.config\n packageName.Main Stanza1\n\nWhere:\n packageName is the directory containing the config file.\n packageName.config specifies the config file in the Java package, packageName.\n packageName.Main specifies Main.java in the Java package, packageName.\n Stanza1 is the name of the stanza Main() should read from the config file.\n```\n\n- When executed, the 1st command-line argument is the stanza from the config file. The Stanza names the `LoginModule` to be used. The 2nd argument is the `CallbackHandler`.\n- Create a new `LoginContext` with the arguments passed to `Main.java`.\n - `loginContext = new LoginContext (args[0], new AppCallbackHandler());`\n- Call the LoginContext.Login Module:\n - `loginContext.login();`\n- The value in succeeded Option is returned from `loginContext.login()`.\n- If the login was successful, a subject was created.\n\n## LoginModule.java\n\nA `LoginModule` must have the following authentication methods:\n\n- `initialize()`\n- `login()`\n- `commit()`\n- `abort()`\n- `logout()`\n\n### initialize()\n\nIn `Main()`, after the `LoginContext` reads the correct stanza from the config file, the `LoginContext` instantiates the `LoginModule` specified in the stanza.\n\n- `initialize()` methods signature:\n - `Public void initialize (Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options)`\n- The arguments above should be saved as follows:\n - `this.subject = subject;`\n - `this.callbackHandler = callbackHandler;`\n - `this.sharedState = sharedState;`\n - `this.options = options;`\n- What the `initialize()` method does:\n - Builds a subject object of the `Subject` class contingent on a successful `login()`.\n - Sets the `CallbackHandler` which interacts with the user to gather login information.\n - If a `LoginContext` specifies 2 or more LoginModules, which is legal, they can share information via a `sharedState` map.\n - Saves state information such as debug and succeeded in an options Map.\n\n### login()\n\nCaptures user supplied login information. The code snippet below declares an array of two callback objects which, when passed to the `callbackHandler.handle` method in the `callbackHandler.java` program, will be loaded with a username and password provided interactively by the user:\n\n```java\nNameCallback nameCB = new NameCallback(\"Username\");\nPasswordCallback passwordCB = new PasswordCallback (\"Password\", false);\nCallback[] callbacks = new Callback[] { nameCB, passwordCB };\ncallbackHandler.handle (callbacks);\n```\n\n- Authenticates the user\n- Retrieves the user supplied information from the callback objects:\n - `String ID = nameCallback.getName ();`\n - `char[] tempPW = passwordCallback.getPassword ();`\n- Compare `name` and `tempPW` to values stored in a repository such as LDAP.\n- Set the value of the variable succeeded and return to `Main()`.\n\n### commit()\n\nOnce the users credentials are successfully verified during `login()`, the JAAS authentication framework associates the credentials, as needed, with the subject.\n\nThere are two types of credentials, **Public** and **Private**:\n\n- Public credentials include public keys.\n- Private credentials include passwords and public keys.\n\nPrincipals (i.e. Identities the subject has other than their login name) such as employee number or membership ID in a user group are added to the subject.\n\nBelow, is an example `commit()` method where first, for each group the authenticated user has membership in, the group name is added as a principal to the subject. The subject's username is then added to their public credentials.\n\nCode snippet setting then adding any principals and a public credentials to a subject:\n\n```java\npublic boolean commit() {\n If (userAuthenticated) {\n Set groups = UserService.findGroups (username);\n for (Iterator itr = groups.iterator (); itr.hasNext (); {\n String groupName = (String) itr.next ();\n UserGroupPrincipal group = new UserGroupPrincipal (GroupName);\n subject.getPrincipals ().add (group);\n }\n UsernameCredential cred = new UsernameCredential (username);\n subject.getPublicCredentials().add (cred);\n }\n}\n```\n\n### abort()\n\nThe `abort()` method is called when authentication doesn't succeed. Before the `abort()` method exits the `LoginModule`, care should be taken to reset state including the username and password input fields.\n\n### logout()\n\nThe release of the users principals and credentials when `LoginContext.logout` is called:\n\n```java\npublic boolean logout() {\n if (!subject.isReadOnly()) {\n Set principals = subject.getPrincipals(UserGroupPrincipal.class);\n subject.getPrincipals().removeAll(principals);\n Set creds = subject.getPublicCredentials(UsernameCredential.class);\n subject.getPublicCredentials().removeAll(creds);\n return true;\n } else {\n return false;\n }\n}\n```\n\n## CallbackHandler.java\n\nThe `callbackHandler` is in a source (`.java`) file separate from any single `LoginModule` so that it can service a multitude of LoginModules with differing callback objects:\n\n- Creates instance of the `CallbackHandler` class and has only one method, `handle()`.\n- A `CallbackHandler` servicing a LoginModule requiring username & password to login:\n\n```java\npublic void handle(Callback[] callbacks) {\n for (int i = 0; i < callbacks.length; i++) {\n Callback callback = callbacks[i];\n if (callback instanceof NameCallback) {\n NameCallback nameCallBack = (NameCallback) callback;\n nameCallBack.setName(username);\n } else if (callback instanceof PasswordCallback) {\n PasswordCallback passwordCallBack = (PasswordCallback) callback;\n passwordCallBack.setPassword(password.toCharArray());\n }\n }\n}\n```"
},
{
"path": "sources/owasp/codeguard-0-java-security.md",
"content": "---\ndescription: Java Security Best Practices\nlanguages:\n- c\n- java\n- javascript\n- typescript\n- xml\n- yaml\nalwaysApply: false\n---\n\n## Java Security Guidelines\n\nKey security practices for secure Java application development.\n\n### SQL Injection Prevention\n\nUse parameterized queries to prevent SQL injection:\n\n```java\n// Safe - PreparedStatement with parameters\nString query = \"select * from color where friendly_name = ?\";\ntry (PreparedStatement pStatement = con.prepareStatement(query)) {\n pStatement.setString(1, userInput);\n try (ResultSet rSet = pStatement.executeQuery()) {\n // Process results\n }\n}\n```\n\n### JPA Query Security\n\nUse parameterized JPA queries:\n\n```java\n// Safe - Named parameters\nString queryPrototype = \"select c from Color c where c.friendlyName = :colorName\";\nQuery queryObject = entityManager.createQuery(queryPrototype);\nColor c = (Color) queryObject.setParameter(\"colorName\", userInput).getSingleResult();\n```\n\n### XSS Prevention\n\nApply input validation and output encoding:\n\n```java\n// Input validation with allowlist\nif (!Pattern.matches(\"[a-zA-Z0-9\\\\s\\\\-]{1,50}\", userInput)) {\n return false;\n}\n\n// Output sanitization\nPolicyFactory policy = new HtmlPolicyBuilder().allowElements(\"p\", \"strong\").toFactory();\nString safeOutput = policy.sanitize(outputToUser);\nsafeOutput = Encode.forHtml(safeOutput);\n```\n\n### Secure Logging\n\nUse parameterized logging to prevent log injection:\n\n```java\n// Safe - parameterized logging\nlogger.warn(\"Login failed for user {}.\", username);\n\n// Avoid - string concatenation\n// logger.warn(\"Login failed for user \" + username);\n```\n\n### Cryptography Best Practices\n\nUse trusted cryptographic libraries and secure algorithms:\n\n```java\n// Use AES-GCM with proper nonce management\nCipher cipher = Cipher.getInstance(\"AES/GCM/NoPadding\");\nGCMParameterSpec gcmParameterSpec = new GCMParameterSpec(128, nonce);\ncipher.init(Cipher.ENCRYPT_MODE, secretKey, gcmParameterSpec);\n\n// Generate secure random nonces\nbyte[] nonce = new byte[12];\nSecureRandom.getInstanceStrong().nextBytes(nonce);\n```\n\n### Key Security Requirements\n\n- Never hardcode cryptographic keys in source code\n- Use Google Tink or similar trusted crypto libraries when possible\n- Avoid writing custom cryptographic implementations\n- Implement proper key rotation and management\n- Keep all dependencies updated with security patches"
},
{
"path": "sources/owasp/codeguard-0-json-web-token-for-java.md",
"content": "---\ndescription: JSON Web Token Security for Java\nlanguages:\n- c\n- java\n- javascript\n- typescript\n- xml\n- yaml\nalwaysApply: false\n---\n\n## JSON Web Token Security for Java\n\nKey security practices for implementing JWT in Java applications.\n\n### Algorithm Security\n\nAlways specify the expected algorithm explicitly:\n\n```java\n// Prevent 'none' algorithm attack\nJWTVerifier verifier = JWT.require(Algorithm.HMAC256(keyHMAC)).build();\nDecodedJWT decodedToken = verifier.verify(token);\n```\n\n### Token Sidejacking Prevention\n\nCode to create the token after successful authentication.\n\n``` java\n// HMAC key - Block serialization and storage as String in JVM memory\nprivate transient byte[] keyHMAC = ...;\n// Random data generator\nprivate SecureRandom secureRandom = new SecureRandom();\n\n...\n\n//Generate a random string that will constitute the fingerprint for this user\nbyte[] randomFgp = new byte[50];\nsecureRandom.nextBytes(randomFgp);\nString userFingerprint = DatatypeConverter.printHexBinary(randomFgp);\n\n//Add the fingerprint in a hardened cookie - Add cookie manually because\n//SameSite attribute is not supported by javax.servlet.http.Cookie class\nString fingerprintCookie = \"__Secure-Fgp=\" + userFingerprint\n + \"; SameSite=Strict; HttpOnly; Secure\";\nresponse.addHeader(\"Set-Cookie\", fingerprintCookie);\n\n//Compute a SHA256 hash of the fingerprint in order to store the\n//fingerprint hash (instead of the raw value) in the token\n//to prevent an XSS to be able to read the fingerprint and\n//set the expected cookie itself\nMessageDigest digest = MessageDigest.getInstance(\"SHA-256\");\nbyte[] userFingerprintDigest = digest.digest(userFingerprint.getBytes(\"utf-8\"));\nString userFingerprintHash = DatatypeConverter.printHexBinary(userFingerprintDigest);\n\n//Create the token with a validity of 15 minutes and client context (fingerprint) information\nCalendar c = Calendar.getInstance();\nDate now = c.getTime();\nc.add(Calendar.MINUTE, 15);\nDate expirationDate = c.getTime();\nMap headerClaims = new HashMap<>();\nheaderClaims.put(\"typ\", \"JWT\");\nString token = JWT.create().withSubject(login)\n .withExpiresAt(expirationDate)\n .withIssuer(this.issuerID)\n .withIssuedAt(now)\n .withNotBefore(now)\n .withClaim(\"userFingerprint\", userFingerprintHash)\n .withHeader(headerClaims)\n .sign(Algorithm.HMAC256(this.keyHMAC));\n```\n\nCode to validate the token.\n\n``` java\n// HMAC key - Block serialization and storage as String in JVM memory\nprivate transient byte[] keyHMAC = ...;\n\n...\n\n//Retrieve the user fingerprint from the dedicated cookie\nString userFingerprint = null;\nif (request.getCookies() != null && request.getCookies().length > 0) {\n List cookies = Arrays.stream(request.getCookies()).collect(Collectors.toList());\n Optional cookie = cookies.stream().filter(c -> \"__Secure-Fgp\"\n .equals(c.getName())).findFirst();\n if (cookie.isPresent()) {\n userFingerprint = cookie.get().getValue();\n }\n}\n\n//Compute a SHA256 hash of the received fingerprint in cookie in order to compare\n//it to the fingerprint hash stored in the token\nMessageDigest digest = MessageDigest.getInstance(\"SHA-256\");\nbyte[] userFingerprintDigest = digest.digest(userFingerprint.getBytes(\"utf-8\"));\nString userFingerprintHash = DatatypeConverter.printHexBinary(userFingerprintDigest);\n\n//Create a verification context for the token\nJWTVerifier verifier = JWT.require(Algorithm.HMAC256(keyHMAC))\n .withIssuer(issuerID)\n .withClaim(\"userFingerprint\", userFingerprintHash)\n .build();\n\n//Verify the token, if the verification fail then an exception is thrown\nDecodedJWT decodedToken = verifier.verify(token);\n```\n\n\n### Token Revocation\n\nImplement token blacklist for logout functionality:\n\n\nCode in charge of adding a token to the denylist and checking if a token is revoked.\n\n``` java\n/**\n* Handle the revocation of the token (logout).\n* Use a DB in order to allow multiple instances to check for revoked token\n* and allow cleanup at centralized DB level.\n*/\npublic class TokenRevoker {\n\n /** DB Connection */\n @Resource(\"jdbc/storeDS\")\n private DataSource storeDS;\n\n /**\n * Verify if a digest encoded in HEX of the ciphered token is present\n * in the revocation table\n *\n * @param jwtInHex Token encoded in HEX\n * @return Presence flag\n * @throws Exception If any issue occur during communication with DB\n */\n public boolean isTokenRevoked(String jwtInHex) throws Exception {\n boolean tokenIsPresent = false;\n if (jwtInHex != null && !jwtInHex.trim().isEmpty()) {\n //Decode the ciphered token\n byte[] cipheredToken = DatatypeConverter.parseHexBinary(jwtInHex);\n\n //Compute a SHA256 of the ciphered token\n MessageDigest digest = MessageDigest.getInstance(\"SHA-256\");\n byte[] cipheredTokenDigest = digest.digest(cipheredToken);\n String jwtTokenDigestInHex = DatatypeConverter.printHexBinary(cipheredTokenDigest);\n\n //Search token digest in HEX in DB\n try (Connection con = this.storeDS.getConnection()) {\n String query = \"select jwt_token_digest from revoked_token where jwt_token_digest = ?\";\n try (PreparedStatement pStatement = con.prepareStatement(query)) {\n pStatement.setString(1, jwtTokenDigestInHex);\n try (ResultSet rSet = pStatement.executeQuery()) {\n tokenIsPresent = rSet.next();\n }\n }\n }\n }\n\n return tokenIsPresent;\n }\n\n\n### Secure Client Storage\n\nStore tokens in sessionStorage with fingerprint binding:\n\n```javascript\n// Store in sessionStorage, not localStorage\nsessionStorage.setItem(\"token\", data.token);\n\n// Send as Bearer token\nxhr.setRequestHeader(\"Authorization\", \"bearer \" + token);\n```\n\n### Strong Secrets\n\nUse strong HMAC secrets or RSA keys:\n- HMAC secrets: minimum 64 characters, cryptographically random\n- Prefer RSA or ECDSA over HMAC for better security\n- Never hardcode secrets in source code"
},
{
"path": "sources/owasp/codeguard-0-key-management.md",
"content": "---\ndescription: Cryptographic Key Management Security\nlanguages:\n- c\n- go\n- java\n- javascript\n- kotlin\n- python\n- ruby\n- swift\n- typescript\nalwaysApply: false\n---\n\n## Key Management Security Guidelines\n\nEssential practices for secure cryptographic key management in applications.\n\n### Key Generation\n\nCryptographic keys shall be generated within cryptographic module with at least FIPS 140-2 compliance. Any random value required by the key-generating module shall be generated within that module using a Random Bit Generator implemented within the cryptographic module.\n\nHardware cryptographic modules are preferred over software cryptographic modules for protection.\n\n### Key Storage\n\n- Keys must be protected on both volatile and persistent memory, ideally processed within secure cryptographic modules\n- Keys should never be stored in plaintext format\n- Ensure all keys are stored in a cryptographic vault, such as a hardware security module (HSM) or isolated cryptographic service\n- When storing keys in offline devices/databases, encrypt the keys using Key Encryption Keys (KEKs) prior to export\n- KEK length and algorithm should be equivalent to or greater in strength than the keys being protected\n- Ensure that standard application level code never reads or uses cryptographic keys directly\n\n### Key Usage and Separation\n\nAccording to NIST, in general, a single key should be used for only one purpose (e.g., encryption, authentication, key wrapping, random number generation, or digital signatures).\n\nReasons for key separation:\n- The use of the same key for two different cryptographic processes may weaken the security provided\n- Limiting the use of a key limits the damage that could be done if the key is compromised\n- Some uses of keys interfere with each other\n\n### Memory Management\n\nKeys stored in memory for a long time can become \"burned in\". This can be mitigated by splitting the key into components that are frequently updated.\n\nPlan for the recovery from possible corruption of the memory media necessary for key or certificate generation, registration, and distribution systems.\n\n### Key Backup and Recovery\n\nData that has been encrypted with lost cryptographic keys will never be recovered. Therefore, it is essential that applications incorporate a secure key backup capability.\n\nWhen backing up keys, ensure that the database used to store the keys is encrypted using at least a FIPS 140-2 validated module.\n\nNever escrow keys used for performing digital signatures, but consider the need to escrow keys that support encryption.\n\n### Trust Store Security\n\n- Design controls to secure the trust store against injection of third-party root certificates\n- Implement integrity controls on objects stored in the trust store\n- Do not allow for export of keys held within the trust store without authentication and authorization\n- Setup strict policies and procedures for exporting key material\n- Implement a secure process for updating the trust store\n\n### Key Security Requirements\n\n- Generate keys only in FIPS 140-2 validated modules or HSMs\n- Use NIST-approved algorithms with appropriate key lengths\n- Never reuse keys for different cryptographic purposes\n- Implement key rotation and lifecycle management\n- Use ephemeral keys for Perfect Forward Secrecy\n- Monitor and audit all key access operations\n- Use only reputable crypto libraries that are well maintained and validated by third-party organizations"
},
{
"path": "sources/owasp/codeguard-0-kubernetes-security.md",
"content": "---\ndescription: Kubernetes Security Best Practices\nlanguages:\n- javascript\n- shell\n- yaml\nalwaysApply: false\n---\n\n## Kubernetes Security Guidelines\n\nEssential security practices for secure Kubernetes cluster deployment and management.\n\n### Host and Component Security\n\nKeep Kubernetes components updated to the latest stable version. The Kubernetes project maintains release branches for the most recent three minor releases with security fixes.\n\nSecure critical components:\n- Restrict access to etcd with mutual TLS authentication and firewall isolation\n- Use strong credentials between API servers and etcd\n- Control network access to sensitive ports (6443 for API server, 2379-2380 for etcd)\n- Enable Kubelet authentication and authorization to prevent unauthenticated access\n\n### Build Phase Security\n\nUse approved, scanned container images from trusted registries:\n- Store approved images in private registries\n- Integrate vulnerability scanning into CI pipeline to block vulnerable images\n- Use minimal base images (distroless when possible) to reduce attack surface\n- Remove shells and package managers from runtime containers\n\n### Deploy Phase Security\n\n#### Pod Security Configuration\n\nApply security context to control pod security parameters:\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n name: hello-world\nspec:\n containers:\n # specification of the pod's containers\n # ...\n # Security Context\n securityContext:\n readOnlyRootFilesystem: true\n runAsNonRoot: true\n```\n\n#### Pod Security Standards\n\nUse Pod Security Admission Controller with namespace-level enforcement:\n\n```yaml\napiVersion: v1\nkind: Namespace\nmetadata:\n name: policy-test\n labels: \n pod-security.kubernetes.io/enforce: restricted\n pod-security.kubernetes.io/audit: restricted\n pod-security.kubernetes.io/warn: restricted\n```\n\nThree security profiles available:\n- **Privileged**: Unrestricted (system workloads only)\n- **Baseline**: Minimally restrictive, prevents known privilege escalations\n- **Restricted**: Most restrictive, enforces current pod hardening practices\n\n#### Network Security\n\nImplement network policies to control pod-to-pod communication:\n\n```json\nPOST /apis/net.alpha.kubernetes.io/v1alpha1/namespaces/tenant-a/networkpolicys\n{\n \"kind\": \"NetworkPolicy\",\n \"metadata\": {\n \"name\": \"pol1\"\n },\n \"spec\": {\n \"allowIncoming\": {\n \"from\": [{\n \"pods\": { \"segment\": \"frontend\" }\n }],\n \"toPorts\": [{\n \"port\": 80,\n \"protocol\": \"TCP\"\n }]\n },\n \"podSelector\": {\n \"segment\": \"backend\"\n }\n }\n}\n```\n\n#### Resource Management\n\nDefine resource quotas to prevent DoS attacks:\n\n```yaml\napiVersion: v1\nkind: ResourceQuota\nmetadata:\n name: compute-resources\nspec:\n hard:\n pods: \"4\"\n requests.cpu: \"1\"\n requests.memory: 1Gi\n limits.cpu: \"2\"\n limits.memory: 2Gi\n```\n\n### Secrets Management\n\n- Mount secrets as read-only volumes rather than environment variables\n- Store secrets separately from images and pods\n- Enable encryption at rest for Secret resources in etcd\n- Consider external secrets managers for multi-cluster environments\n\n### Runtime Phase Security\n\n#### Monitoring and Detection\n\nMonitor container behavior for security anomalies:\n- Shell execution inside containers\n- Sensitive file access (e.g., /etc/shadow)\n- Unexpected network connections\n- Process activity deviations between replicas\n\n#### Audit Logging\n\nEnable Kubernetes audit logging to track API requests:\n\n```json\n{\n \"kind\":\"Event\",\n \"apiVersion\":\"audit.k8s.io/v1beta1\",\n \"metadata\":{ \"creationTimestamp\":\"2019-08-22T12:00:00Z\" },\n \"level\":\"Metadata\",\n \"timestamp\":\"2019-08-22T12:00:00Z\",\n \"auditID\":\"23bc44ds-2452-242g-fsf2-4242fe3ggfes\",\n \"stage\":\"RequestReceived\",\n \"requestURI\":\"/api/v1/namespaces/default/persistentvolumeclaims\",\n \"verb\":\"list\",\n \"user\": {\n \"username\":\"user@example.org\",\n \"groups\":[ \"system:authenticated\" ]\n },\n \"sourceIPs\":[ \"172.12.56.1\" ]\n}\n```\n\n### Access Control\n\n- Implement RBAC with least privilege principles\n- Use external authentication (OIDC) with multi-factor authentication\n- Avoid built-in authentication methods for production clusters\n- Secure the Kubernetes Dashboard with authenticating reverse proxy\n\n### Key Security Requirements\n\n- Always run the latest stable Kubernetes version\n- Use namespaces to isolate workloads\n- Apply security contexts to prevent privileged container execution\n- Implement network policies for traffic segmentation\n- Enable comprehensive audit logging and monitoring\n- Rotate credentials frequently and revoke bootstrap tokens promptly\n- Use admission controllers to enforce security policies"
},
{
"path": "sources/owasp/codeguard-0-laravel.md",
"content": "---\ndescription: Laravel Security Best Practices\nlanguages:\n- c\n- javascript\n- php\n- typescript\n- yaml\nalwaysApply: false\n---\n\n## Laravel Security Guidelines\n\nEssential security practices for building secure Laravel applications.\n\n### Basic Configuration\n\nDisable debug mode in production and generate application key:\n\n```ini\nAPP_DEBUG=false\n```\n\n```bash\nphp artisan key:generate\n```\n\nSet secure file permissions: directories `775`, files `664`, executables `775`.\n\n### Cookie Security and Session Management\n\nEnable cookie encryption middleware in `App\\Http\\Kernel`:\n\n```php\nprotected $middlewareGroups = [\n 'web' => [\n \\App\\Http\\Middleware\\EncryptCookies::class,\n ...\n ],\n ...\n];\n```\n\nConfigure secure session settings in `config/session.php`:\n\n```php\n'http_only' => true,\n'domain' => null,\n'same_site' => 'lax',\n'secure' => null,\n'lifetime' => 15,\n```\n\n### Mass Assignment Protection\n\nProtect against mass assignment vulnerabilities:\n\n```php\n// VULNERABLE: Allows modification of any field\nRoute::any('/profile', function (Request $request) {\n $request->user()->forceFill($request->all())->save();\n return response()->json(compact('user'));\n})->middleware('auth');\n```\n\nUse `$request->only()` or `$request->validated()` instead of `$request->all()`.\n\n### SQL Injection Prevention\n\nUse Eloquent ORM parameterized queries by default. For raw queries, always use bindings:\n\n```php\n// VULNERABLE: No SQL bindings\nUser::whereRaw('email = \"'.$request->input('email').'\"')->get();\n\n// SAFE: Using SQL bindings\nUser::whereRaw('email = ?', [$request->input('email')])->get();\n\n// SAFE: Named bindings\nUser::whereRaw('email = :email', ['email' => $request->input('email')])->get();\n```\n\nValidate column names to prevent column name injection:\n\n```php\n$request->validate(['sortBy' => 'in:price,updated_at']);\nUser::query()->orderBy($request->validated()['sortBy'])->get();\n```\n\n### XSS Prevention\n\nUse Blade's automatic escaping for all untrusted data:\n\n```blade\n{{-- SAFE: Automatically escaped --}}\n{{ request()->input('somedata') }}\n\n{{-- VULNERABLE: Unescaped data --}}\n{!! request()->input('somedata') !!}\n```\n\n### File Upload Security\n\nAlways validate file type and size:\n\n```php\n$request->validate([\n 'photo' => 'file|size:100|mimes:jpg,bmp,png'\n]);\n```\n\nSanitize filenames to prevent path traversal:\n\n```php\nRoute::post('/upload', function (Request $request) {\n $request->file('file')->storeAs(auth()->id(), basename($request->input('filename')));\n return back();\n});\n```\n\n### Path Traversal Prevention\n\nUse `basename()` to strip directory information:\n\n```php\nRoute::get('/download', function(Request $request) {\n return response()->download(storage_path('content/').basename($request->input('filename')));\n});\n```\n\n### CSRF Protection\n\nEnable CSRF middleware and use tokens in forms:\n\n```php\nprotected $middlewareGroups = [\n 'web' => [\n ...\n \\App\\Http\\Middleware\\VerifyCsrfToken::class,\n ...\n ],\n];\n```\n\n```html\n\n```\n\n### Command Injection Prevention\n\nEscape shell commands with user input:\n\n```php\npublic function verifyDomain(Request $request)\n{\n exec('whois '.$request->input('domain'));\n}\n```\n\nUse `escapeshellcmd` and `escapeshellarg` for proper escaping.\n\n### Rate Limiting\n\nApply throttling to protect against abuse:\n\n```php\nRoute::get('/profile', function () {\n return 'User profile';\n})->middleware('throttle:10,1'); // 10 requests per minute\n\n// Custom rate limiter\nRateLimiter::for('custom-limit', function ($request) {\n return Limit::perMinute(5)->by($request->user()?->id ?: $request->ip());\n});\n```\n\n### Other Injection Prevention\n\nAvoid dangerous functions with untrusted input:\n\n```php\nunserialize($request->input('data'));\neval($request->input('data'));\nextract($request->all());\n```\n\n### Security Auditing\n\nUse Enlightn Security Checker to scan for vulnerabilities and keep dependencies updated."
},
{
"path": "sources/owasp/codeguard-0-ldap-injection-prevention.md",
"content": "---\ndescription: LDAP Injection Prevention\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\n- xml\n- yaml\nalwaysApply: false\n---\n\n## LDAP Injection Prevention Guidelines\n\nEssential practices for preventing LDAP injection vulnerabilities in applications that use directory services.\n\n### Understanding LDAP Injection\n\nLDAP injection occurs when untrusted user input is improperly incorporated into LDAP queries, potentially allowing attackers to bypass authentication, access unauthorized data, or modify directory information.\n\nTwo main components vulnerable to injection:\n- **Distinguished Names (DNs)**: Unique identifiers like `cn=Richard Feynman, ou=Physics Department, dc=Caltech, dc=edu`\n- **Search Filters**: Query criteria using boolean logic in Polish notation\n\n### Primary Defense: Proper Escaping\n\n#### Distinguished Name Escaping\n\nCharacters that must be escaped in DNs: `\\ # + < > , ; \" =` and leading or trailing spaces.\n\nCharacters allowed in DNs (no escaping needed): `* ( ) . & - _ [ ] ` ~ | @ $ % ^ ? : { } ! '`\n\n#### Search Filter Escaping\n\nCharacters that must be escaped in search filters: `* ( ) \\ NUL`\n\n### Safe Java Example\n\nThe original OWASP document provides this allowlist validation approach:\n\n```java\n// String userSN = \"Sherlock Holmes\"; // Valid\n// String userPassword = \"secret2\"; // Valid\n// ... beginning of LDAPInjection.searchRecord()...\nsc.setSearchScope(SearchControls.SUBTREE_SCOPE);\nString base = \"dc=example,dc=com\";\n\nif (!userSN.matches(\"[\\\\w\\\\s]*\") || !userPassword.matches(\"[\\\\w]*\")) {\n throw new IllegalArgumentException(\"Invalid input\");\n}\n\nString filter = \"(&(sn = \" + userSN + \")(userPassword=\" + userPassword + \"))\";\n// ... remainder of LDAPInjection.searchRecord()... \n```\n\n### Safe .NET Encoding\n\nUse .NET AntiXSS (now the Encoder class) LDAP encoding functions:\n- `Encoder.LdapFilterEncode(string)` - encodes according to RFC4515\n- `Encoder.LdapDistinguishedNameEncode(string)` - encodes according to RFC2253\n- `LdapDistinguishedNameEncode(string, bool, bool)` - with optional initial/final character escaping\n\n### Framework-Based Protection\n\nUse frameworks that automatically protect from LDAP injection:\n- **Java**: OWASP ESAPI with `encodeForLDAP(String)` and `encodeForDN(String)`\n- **.NET**: LINQ to LDAP (for .NET Framework 4.5 or lower) provides automatic LDAP encoding\n\n### Additional Defenses\n\n#### Least Privilege\n- Minimize privileges assigned to LDAP binding accounts\n- Use read-only accounts where possible\n- Avoid administrative accounts for application connections\n\n#### Bind Authentication\n- Configure LDAP with bind authentication to add verification and authorization checks\n- Prevent anonymous connections and unauthenticated binds\n\n#### Allow-List Input Validation\n- Validate input against known-safe characters before LDAP query construction\n- Normalize user input before validation\n- Store sensitive data in sanitized form\n\n### Key Security Requirements\n\n- Always escape untrusted data before incorporating into LDAP queries\n- Use context-appropriate escaping (DN vs search filter)\n- Implement comprehensive input validation with allowlists\n- Use established security libraries rather than custom escaping\n- Apply principle of least privilege to LDAP connections\n- Enable proper authentication mechanisms to prevent bypass attacks"
},
{
"path": "sources/owasp/codeguard-0-legacy-application-management.md",
"content": "---\ndescription: Legacy Application Management Security\nlanguages:\n- c\n- java\n- javascript\n- perl\n- php\n- python\n- ruby\n- yaml\nalwaysApply: false\n---\n\n## Legacy Application Management Guidelines\n\nEssential security practices for managing legacy applications that remain in active use despite being outdated.\n\n### Understanding Legacy Application Risks\n\nLegacy applications introduce significant security risks because they:\n- May have reached End-of-Life (EoL) with no vendor support or patches\n- Use outdated technologies with limited expertise available\n- Produce data in custom formats incompatible with modern security tools\n- Often have accumulated security vulnerabilities over time\n\n### Inventory and Asset Management\n\n**Inventory Management**: Compile comprehensive documentation identifying legacy applications including:\n- Version numbers, production dates, and configuration settings\n- Network hosts and infrastructure dependencies\n- Services running on hosting infrastructure\n- Physical location and access permissions for servers\n- Software Bill of Materials (SBOM) for applications with third-party dependencies\n\n**Risk Assessment**: Use industry standard frameworks like NIST Risk Management Framework for formal assessment. Consider these key questions:\n- What information is handled/stored and what would be the impact if compromised?\n- Do the application/dependencies/infrastructure have known vulnerabilities?\n- How critical is application availability to business continuity?\n- Could an attacker use this application to access other critical systems?\n\n### Authentication and Authorization\n\nApply the principle of least privilege with enhanced restrictions for legacy systems:\n\n**Network-Level Controls**:\n- Host applications within restricted subnets\n- Apply IP allow-listing to prevent arbitrary access\n- Consider air-gapped environments for high-risk applications\n- Close unnecessary ports on application hosts\n- Use firewall rules to restrict port access\n\n**Access Controls**:\n- Reduce feature sets available to end users\n- Disable high-risk administrative functionalities\n- Require authentication via Identity Provider (IdP) services\n- Implement VPN access requirements for network environments\n- Develop intermediary services/APIs to avoid direct user access to legacy applications\n\n### Vulnerability Management\n\n**Vulnerability Scanning**: Conduct regular automated scanning using industry standard tools:\n- Use tools like Nessus and Qualys on scheduled intervals\n- Apply Static Application Security Testing (SAST) for code vulnerabilities\n- Use Software Composition Analysis (SCA) for dependency vulnerabilities\n- Perform manual assessment when automated tools aren't viable\n\n**Patch Management**: \n- Prioritize patches based on vulnerability severity and CVE status\n- Focus on vulnerabilities with publicly listed exploits\n- Apply additional access restrictions when patching isn't possible\n\n### Data Storage Security\n\nEnsure data protection through encryption:\n- Encrypt data at rest (database storage)\n- Encrypt data in transit with secure protocols\n- Apply most restrictive network access controls for applications limited to plain text protocols\n- Consider temporary or permanent air-gapping when necessary\n\n### Ensuring Maintainability\n\nMaintain institutional expertise for business continuity:\n- Train multiple staff members on legacy application troubleshooting\n- Document processes and troubleshooting guides for common failures\n- Develop expertise in legacy programming languages within the organization\n- Create knowledge transfer programs for new team members\n\n### Change Management\n\nPlan staged migration to modern solutions considering:\n- Budget allocation and timeline for upgrading solutions\n- Required expertise for migration (internal development or acquisition)\n- Migration urgency based on risk profile and organizational risk appetite\n\nInclude in change management plans:\n- Granular steps toward migration with explicit completion dates\n- Clear business and security case for change\n- Extensive consultation with existing solution stakeholders\n\n### Continuous Monitoring and Incident Response\n\nImplement enhanced security monitoring with rapid response capabilities:\n\n**Monitoring Solutions**:\n- Develop custom APIs to convert legacy application data for modern security tools\n- Use automation scripts for compromise indicator reports when APIs aren't possible\n- Monitor for anomalous network traffic and activity surges\n\n**Incident Response**:\n- Prioritize incident response for critical legacy systems\n- Document incident response playbooks with emergency procedures\n- Include escalation contacts and incident response leader details\n- Integrate incident response with broader business continuity planning\n\nLegacy applications require heightened security measures due to their inherent risks, but with proper controls and planning, organizations can manage these risks while working toward modernization."
},
{
"path": "sources/owasp/codeguard-0-logging-vocabulary.md",
"content": "---\ndescription: Standardized Security Event Logging Vocabulary\nlanguages:\n- c\n- go\n- java\n- javascript\n- kotlin\n- php\n- python\n- ruby\n- swift\n- typescript\nalwaysApply: false\n---\n\n## Security Event Logging Vocabulary Guidelines\n\nStandardized vocabulary for logging security events to improve monitoring, alerting, and incident response.\n\n### Standard Event Format\n\nNOTE: All dates should be logged in ISO 8601 format WITH UTC offset to ensure maximum portability\n\n```json\n{\n \"datetime\": \"2021-01-01T01:01:01-0700\",\n \"appid\": \"foobar.netportal_auth\",\n \"event\": \"AUTHN_login_success:joebob1\",\n \"level\": \"INFO\",\n \"description\": \"User joebob1 login successfully\",\n \"useragent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.108 Safari/537.36\",\n \"source_ip\": \"165.225.50.94\",\n \"host_ip\": \"10.12.7.9\",\n \"hostname\": \"portalauth.foobar.com\",\n \"protocol\": \"https\",\n \"port\": \"440\",\n \"request_uri\": \"/api/v2/auth/\",\n \"request_method\": \"POST\",\n \"region\": \"AWS-US-WEST-2\",\n \"geo\": \"USA\"\n}\n```\n\n### Authentication Events [AUTHN]\n\nauthn_login_success[:userid] - Successful login (Level: INFO)\nauthn_login_successafterfail[:userid,retries] - Successful login after previous failures (Level: INFO)\nauthn_login_fail[:userid] - Failed login attempt (Level: WARN)\nauthn_login_fail_max[:userid,maxlimit] - Maximum failures reached (Level: WARN)\nauthn_login_lock[:userid,reason] - Account locked (reasons: maxretries, suspicious, customer, other) (Level: WARN)\nauthn_password_change[:userid] - Password successfully changed (Level: INFO)\nauthn_password_change_fail[:userid] - Password change failed (Level: CRITICAL)\nauthn_impossible_travel[:userid,region1,region2] - User in distant locations simultaneously (Level: CRITICAL)\nauthn_token_created[:userid,entitlements] - Service token created (Level: INFO)\nauthn_token_revoked[:userid,tokenid] - Token revoked (Level: INFO)\nauthn_token_reuse[:userid,tokenid] - Revoked token reuse attempt (Level: CRITICAL)\nauthn_token_delete[:appid] - Token deleted (Level: WARN)\n\n### Authorization Events [AUTHZ]\n\nauthz_fail[:userid,resource] - Unauthorized access attempt (Level: CRITICAL)\nauthz_change[:userid,from,to] - User entitlements changed (Level: WARN)\nauthz_admin[:userid,event] - All privileged user activity (Level: WARN)\n\n### Encryption/Decryption Events [CRYPT]\n\ncrypt_decrypt_fail[userid] - Decryption failure (Level: WARN)\ncrypt_encrypt_fail[userid] - Encryption failure (Level: WARN)\n\n### Excessive Use Events [EXCESS]\n\nexcess_rate_limit_exceeded[userid,max] - Rate limit exceeded (Level: WARN)\n\n### File Upload Events [UPLOAD]\n\nupload_complete[userid,filename,type] - File upload completed (Level: INFO)\nupload_stored[filename,from,to] - File stored with new name/location (Level: INFO)\nupload_validation[filename,(virusscan|imagemagick|...):(FAILED|incomplete|passed)] - File validation results (Level: INFO|CRITICAL)\nupload_delete[userid,fileid] - File deleted (Level: INFO)\n\n### Input Validation Events [INPUT]\n\ninput_validation_fail:[(fieldone,fieldtwo...),userid] - Server-side validation failure (Level: WARN)\n\n### Malicious Behavior Events [MALICIOUS]\n\nmalicious_excess_404:[userid|IP,useragent] - Excessive 404s indicating force-browsing (Level: WARN)\nmalicious_extraneous:[userid|IP,inputname,useragent] - Unexpected input data submitted (Level: CRITICAL)\nmalicious_attack_tool:[userid|IP,toolname,useragent] - Known attack tools detected (Level: CRITICAL)\nmalicious_cors:[userid|IP,useragent,referer] - Illegal cross-origin request (Level: CRITICAL)\nmalicious_direct_reference:[userid|IP,useragent] - Direct object reference attempt (Level: CRITICAL)\n\n### Privilege Changes Events [PRIVILEGE]\n\nprivilege_permissions_changed:[userid,file|object,fromlevel,tolevel] - Object permissions changed (Level: WARN)\n\n### Sensitive Data Events [DATA]\n\nsensitive_create:[userid,file|object] - Sensitive data created (Level: WARN)\nsensitive_read:[userid,file|object] - Sensitive data accessed (Level: WARN)\nsensitive_update:[userid,file|object] - Sensitive data modified (Level: WARN)\nsensitive_delete:[userid,file|object] - Sensitive data marked for deletion (Level: WARN)\n\n### Sequence Errors Events [SEQUENCE]\n\nsequence_fail:[userid] - Business logic flow bypassed (Level: CRITICAL)\n\n### Session Management Events [SESSION]\n\nsession_created:[userid] - New authenticated session (Level: INFO)\nsession_renewed:[userid] - Session extended after expiry warning (Level: INFO)\nsession_expired:[userid,reason] - Session expired (reasons: logout, timeout, revoked) (Level: INFO)\nsession_use_after_expire:[userid] - Expired session use attempt (Level: CRITICAL)\n\n### System Events [SYS]\n\nsys_startup:[userid] - System started (Level: WARN)\nsys_shutdown:[userid] - System shut down (Level: WARN)\nsys_restart:[userid] - System restarted (Level: WARN)\nsys_crash[:reason] - System crash (Level: WARN)\nsys_monitor_disabled:[userid,monitor] - Security monitoring disabled (Level: WARN)\nsys_monitor_enabled:[userid,monitor] - Security monitoring enabled (Level: WARN)\n\n### User Management Events [USER]\n\nuser_created:[userid,newuserid,attributes[one,two,three]] - New user created (Level: WARN)\nuser_updated:[userid,onuserid,attributes[one,two,three]] - User account updated (Level: WARN)\nuser_archived:[userid,onuserid] - User account archived (Level: WARN)\nuser_deleted:[userid,onuserid] - User account deleted (Level: WARN)\n\n### Data Exclusions\n\nNever log sensitive information: private or secret information, source code, keys, certificates, authentication passwords, session identification values, access tokens, sensitive personal data, PII, database connection strings, encryption keys, bank account or payment card data, commercially-sensitive information.\n\n### Implementation Requirements\n\n- Use ISO 8601 format with UTC offset for all timestamps\n- Include application identifier (appid) for correlation \n- Apply consistent severity levels (INFO, WARN, CRITICAL)\n- Include relevant context (IP addresses, user agents, request details)\n- Consider data privacy regulations when logging user information\n- Fields logged after event type should be considered optional based on business needs and data stewardship responsibilities"
},
{
"path": "sources/owasp/codeguard-0-mass-assignment.md",
"content": "---\ndescription: Mass Assignment Prevention\nlanguages:\n- c\n- java\n- javascript\n- php\n- ruby\n- scala\nalwaysApply: false\n---\n\n## Mass Assignment Prevention Guidelines\n\nEssential practices for preventing mass assignment vulnerabilities that allow attackers to modify unintended object properties.\n\n### Understanding Mass Assignment\n\nMass assignment occurs when frameworks automatically bind HTTP request parameters to program variables or objects. Attackers can exploit this by creating new parameters to overwrite sensitive fields like `isAdmin` or other privilege-related properties.\n\n**Alternative Names by Framework:**\n- Mass Assignment: Ruby on Rails, NodeJS\n- Autobinding: Spring MVC, ASP NET MVC \n- Object injection: PHP\n\n### Vulnerable Example\n\nUser form with typical fields:\n```html\n\n```\n\nUser object with sensitive field:\n```java\npublic class User {\n private String userid;\n private String password;\n private String email;\n private boolean isAdmin;\n //Getters & Setters\n}\n```\n\nVulnerable controller with automatic binding:\n```java\n@RequestMapping(value = \"/addUser\", method = RequestMethod.POST)\npublic String submit(User user) {\n userService.add(user);\n return \"successPage\";\n}\n```\n\nAttack payload:\n```text\nPOST /addUser\nuserid=bobbytables&password=hashedpass&email=bobby@tables.com&isAdmin=true\n```\n\n### Primary Defense Strategies\n\n**1. Use Data Transfer Objects (DTOs)**\nCreate objects exposing only safe, editable fields:\n\n```java\npublic class UserRegistrationFormDTO {\n private String userid;\n private String password;\n private String email;\n //NOTE: isAdmin field is not present\n //Getters & Setters\n}\n```\n\n**2. Allow-list Approach**\nExplicitly define permitted fields for binding.\n\n**3. Block-list Approach** \nExplicitly exclude sensitive fields from binding.\n\n### Framework-Specific Implementations\n\n#### Spring MVC\n\nAllow-listing permitted fields:\n```java\n@Controller\npublic class UserController {\n @InitBinder\n public void initBinder(WebDataBinder binder, WebRequest request) {\n binder.setAllowedFields([\"userid\",\"password\",\"email\"]);\n }\n}\n```\n\nBlock-listing sensitive fields:\n```java\n@Controller\npublic class UserController {\n @InitBinder\n public void initBinder(WebDataBinder binder, WebRequest request) {\n binder.setDisallowedFields([\"isAdmin\"]);\n }\n}\n```\n\n#### NodeJS + Mongoose\n\nAllow-listing with underscore.js:\n```javascript\nvar UserSchema = new mongoose.Schema({\n userid: String,\n password: String,\n email : String,\n isAdmin : Boolean,\n});\n\nUserSchema.statics = {\n User.userCreateSafeFields: ['userid', 'password', 'email']\n};\n\nvar User = mongoose.model('User', UserSchema);\n\n_ = require('underscore');\nvar user = new User(_.pick(req.body, User.userCreateSafeFields));\n```\n\nBlock-listing with mongoose-mass-assign plugin:\n```javascript\nvar massAssign = require('mongoose-mass-assign');\n\nvar UserSchema = new mongoose.Schema({\n userid: String,\n password: String,\n email : String,\n isAdmin : { type: Boolean, protect: true, default: false }\n});\n\nUserSchema.plugin(massAssign);\nvar User = mongoose.model('User', UserSchema);\n\nvar user = User.massAssign(req.body);\n```\n\n#### PHP Laravel + Eloquent\n\nAllow-listing with $fillable:\n```php\n Received signal to terminate: ${signal}`)\n \n await fastify.close()\n // await db.close() if we have a db connection in this app\n // await other things we should cleanup nicely\n process.exit()\n }\n process.on('SIGINT', closeGracefully)\n process.on('SIGTERM', closeGracefully)\n```\n\n### Use Multi-Stage Builds\n\nSeparate build and production stages to minimize final image size and prevent secret leakage:\n\n```dockerfile\n# --------------> The build image\nFROM node:latest AS build\nWORKDIR /usr/src/app\nCOPY package*.json /usr/src/app/\nRUN --mount=type=secret,mode=0644,id=npmrc,target=/usr/src/app/.npmrc npm ci --omit=dev\n\n# --------------> The production image\nFROM node:lts-alpine@sha256:b2da3316acdc2bec442190a1fe10dc094e7ba4121d029cb32075ff59bb27390a\nRUN apk add dumb-init\nENV NODE_ENV production\nUSER node\nWORKDIR /usr/src/app\nCOPY --chown=node:node --from=build /usr/src/app/node_modules /usr/src/app/node_modules\nCOPY --chown=node:node . /usr/src/app\nCMD [\"dumb-init\", \"node\", \"server.js\"]\n```\n\n### Use .dockerignore File\n\nCreate a `.dockerignore` file to exclude unnecessary and sensitive files:\n```\nnode_modules\nnpm-debug.log\nDockerfile\n.git\n.gitignore\n.npmrc\n```\n\nThis prevents:\n- Copying modified local `node_modules/` over the container-built version\n- Including sensitive files like credentials or local configuration\n- Cache invalidation from log files or temporary files\n\n### Mount Secrets Securely\n\nUse Docker BuildKit secrets to handle sensitive files like `.npmrc`:\n```dockerfile\nRUN --mount=type=secret,mode=0644,id=npmrc,target=/usr/src/app/.npmrc npm ci --omit=dev\n```\n\nBuild command:\n```bash\ndocker build . -t nodejs-tutorial --secret id=npmrc,src=.npmrc\n```\n\nThis ensures secrets are never copied into the final Docker image layers.\n\n### Security Scanning\n\nRegularly scan your Docker images for vulnerabilities using static analysis tools and keep dependencies updated.\n\nBy following these practices, you'll create secure, optimized, and maintainable Node.js Docker images suitable for production deployment."
},
{
"path": "sources/owasp/codeguard-0-nodejs-security.md",
"content": "---\ndescription: Node.js Security Best Practices\nlanguages:\n- c\n- javascript\n- typescript\nalwaysApply: false\n---\n\n## Node.js Security Guidelines\n\nEssential security practices for developing secure Node.js applications to prevent common vulnerabilities and attacks.\n\n### Application Security\n\n#### Use Flat Promise Chains\n\nAvoid callback hell and improve error handling by using flat Promise chains or async/await:\n\n```javascript\n// Avoid callback hell\nfunc1(\"input1\")\n .then(function (result){\n return func2(\"input2\");\n })\n .then(function (result){\n return func3(\"input3\");\n })\n .then(function (result){\n return func4(\"input4\");\n })\n .catch(function (error) {\n // error operations\n });\n```\n\nUsing async/await:\n```javascript\n(async() => {\n try {\n let res1 = await func1(\"input1\");\n let res2 = await func2(\"input2\");\n let res3 = await func3(\"input2\");\n let res4 = await func4(\"input2\");\n } catch(err) {\n // error operations\n }\n})();\n```\n\n#### Set Request Size Limits\n\nPrevent resource exhaustion by limiting request body sizes:\n\n```javascript\napp.use(express.urlencoded({ extended: true, limit: \"1kb\" }));\napp.use(express.json({ limit: \"1kb\" }));\n```\n\nFor custom limits using raw-body:\n```JavaScript\nconst contentType = require('content-type')\nconst express = require('express')\nconst getRawBody = require('raw-body')\n\nconst app = express()\n\napp.use(function (req, res, next) {\n if (!['POST', 'PUT', 'DELETE'].includes(req.method)) {\n next()\n return\n }\n\n getRawBody(req, {\n length: req.headers['content-length'],\n limit: '1kb',\n encoding: contentType.parse(req).parameters.charset\n }, function (err, string) {\n if (err) return next(err)\n req.text = string\n next()\n })\n})\n```\n\n#### Perform Input Validation\n\nUse allowlists and sanitize all inputs to prevent injection attacks. Consider modules like validator and express-mongo-sanitize for input validation.\n\n#### Perform Output Escaping\n\nEscape all HTML and JavaScript content to prevent XSS attacks using libraries like escape-html or node-esapi.\n\n#### Monitor Event Loop Health\n\nUse monitoring to detect when your server is overloaded:\n\n```javascript\nconst toobusy = require('toobusy-js');\napp.use(function(req, res, next) {\n if (toobusy()) {\n res.status(503).send(\"Server Too Busy\");\n } else {\n next();\n }\n});\n```\n\n#### Prevent Brute Force Attacks\n\nImplement rate limiting and delays for authentication endpoints:\n\n```javascript\nconst bouncer = require('express-bouncer');\nbouncer.blocked = function (req, res, next, remaining) {\n res.status(429).send(\"Too many requests have been made. Please wait \" + remaining/1000 + \" seconds.\");\n};\napp.post(\"/login\", bouncer.block, function(req, res) {\n if (LoginFailed){ }\n else {\n bouncer.reset( req );\n }\n});\n```\n\n#### Use Anti-CSRF Protection\n\nProtect state-changing requests against Cross-Site Request Forgery. Note: csurf package is deprecated; use alternative CSRF protection packages.\n\n#### Prevent HTTP Parameter Pollution\n\nUse the hpp module to handle multiple parameters with the same name:\n\n```javascript\nconst hpp = require('hpp');\napp.use(hpp());\n```\n\n#### Return Only Necessary Data\n\nLimit data exposure by returning only required fields:\n\n```javascript\nexports.sanitizeUser = function(user) {\n return {\n id: user.id,\n username: user.username,\n fullName: user.fullName\n };\n};\n```\n\n### Error and Exception Handling\n\n#### Handle Uncaught Exceptions\n\nBind to uncaughtException events to clean up resources before shutdown:\n\n```javascript\nprocess.on(\"uncaughtException\", function(err) {\n // clean up allocated resources\n // log necessary error details to log files\n process.exit(); // exit the process to avoid unknown state\n});\n```\n\n#### Handle EventEmitter Errors\n\nAlways listen to error events when using EventEmitter objects:\n\n```javascript\nconst events = require('events');\nconst emitter = new myEventEmitter();\nemitter.on('error', function(err){\n //Perform necessary error handling here\n});\n```\n\n### Server Security\n\n#### Set Secure Cookie Flags\n\nConfigure cookies with appropriate security flags:\n\n```javascript\nconst session = require('express-session');\napp.use(session({\n secret: 'your-secret-key',\n name: 'cookieName',\n cookie: { secure: true, httpOnly: true, path: '/user', sameSite: true}\n}));\n```\n\n#### Use Security Headers\n\nImplement security headers using helmet:\n\n```javascript\nconst helmet = require(\"helmet\");\napp.use(helmet()); // Add various HTTP headers\n```\n\nKey headers include:\n- HSTS: `app.use(helmet.hsts());`\n- Frame protection: `app.use(helmet.frameguard());`\n- XSS protection: `app.use(helmet.xssFilter());`\n- Content Security Policy: `app.use(helmet.contentSecurityPolicy({...}));`\n- Content type protection: `app.use(helmet.noSniff());`\n- Hide powered by: `app.use(helmet.hidePoweredBy());`\n\n### Platform Security\n\n#### Keep Packages Updated\n\nRegularly audit and update dependencies:\n\n```bash\nnpm audit\nnpm audit fix\n```\n\nUse tools like OWASP Dependency-Check and Retire.js to identify vulnerable packages.\n\n#### Avoid Dangerous Functions\n\nExercise caution with potentially dangerous functions:\n- Avoid `eval()` with user input (remote code execution risk)\n- Be careful with `child_process.exec` (command injection risk)\n- Sanitize inputs when using `fs` module (directory traversal risk)\n- Use `vm` module within proper sandboxes\n\n#### Prevent ReDoS Attacks\n\nTest regular expressions for denial of service vulnerabilities using tools like vuln-regex-detector.\n\n#### Use Security Linters\n\nImplement static analysis tools like ESLint and JSHint with security-focused rules in your development workflow.\n\n#### Enable Strict Mode\n\nAlways use strict mode to catch common JavaScript errors:\n\n```javascript\n\"use strict\";\n\nfunc();\nfunction func() {\n y = 3.14; // This will cause an error (y is not defined)\n}\n```\n\n### Application Activity Logging\n\nImplement comprehensive logging for security monitoring:\n\n```javascript\nconst logger = new (Winston.Logger) ({\n transports: [\n new (winston.transports.Console)(),\n new (winston.transports.File)({ filename: 'application.log' })\n ],\n level: 'verbose'\n});\n```\n\nBy following these practices, you can significantly improve the security posture of your Node.js applications and protect against common web application vulnerabilities."
},
{
"path": "sources/owasp/codeguard-0-npm-security.md",
"content": "---\ndescription: NPM Security Best Practices\nlanguages:\n- javascript\nalwaysApply: false\n---\n\n## NPM Security Guidelines\n\nEssential security practices for managing NPM packages and dependencies in JavaScript projects.\n\n### Prevent Secret Leakage\n\nAvoid publishing sensitive data to the npm registry:\n- Use the `files` property in package.json as an allowlist to control what gets published\n- Be cautious with `.gitignore` and `.npmignore` - if both exist, `.npmignore` takes precedence\n- Run `npm publish --dry-run` to review the tarball contents before actual publishing\n- NPM automatically revokes tokens detected in published packages, but prevention is better\n\n### Enforce Deterministic Builds\n\nEnsure consistent dependency installation across environments:\n- Use `npm ci` instead of `npm install` in CI/CD and production builds\n- Use `yarn install --frozen-lockfile` if using Yarn\n- Never commit changes to package.json without updating the corresponding lockfile\n- Lockfile inconsistencies can pull unintended package versions and compromise security\n\n### Minimize Script Execution Risks\n\nReduce attack surface from package installation scripts:\n- Add `--ignore-scripts` when installing packages: `npm install --ignore-scripts`\n- Consider adding `ignore-scripts=true` to your `.npmrc` configuration\n- Always vet third-party packages for credibility before installation\n- Avoid immediate upgrades to new versions; allow time for community review\n- Review changelog and release notes before upgrading dependencies\n\n### Monitor Package Health\n\nRegularly assess the state of your dependencies:\n- Use `npm outdated` to identify packages that need updates\n- Run `npm doctor` to verify healthy npm installation and environment\n- Monitor for known vulnerabilities in dependencies using `npm audit`\n- Scan for security vulnerabilities in third-party open source projects\n- Set up monitoring for new CVEs that impact your project dependencies\n\n### Use Private Registry Solutions\n\nConsider using local npm proxies for enhanced control:\n- Verdaccio provides a lightweight private registry solution\n- Private registries offer package access control and authenticated users\n- Proxy capabilities reduce duplicate downloads and save bandwidth\n- Enable routing dependencies to different registries for security control\n- Useful for testing environments and mono-repo projects\n\n### Enable Account Security\n\nProtect your npm publishing capabilities:\n- Enable two-factor authentication with `npm profile enable-2fa auth-and-writes`\n- Use auth-and-writes mode for comprehensive protection of profile, login, and package management\n- Auth-only mode provides protection for login and profile changes only\n- Use authentication apps like Google Authenticator for 2FA tokens\n\n### Manage Access Tokens Securely\n\nControl programmatic access to npm registry:\n- Create tokens with minimal required permissions using `npm token create`\n- Use read-only tokens when write access is not needed\n- Restrict tokens to specific IP ranges with `--cidr` option\n- Regularly audit tokens with `npm token list`\n- Revoke unused or compromised tokens immediately with `npm token revoke`\n- Never expose tokens in source code, logs, or environment variables\n\n### Defend Against Typosquatting\n\nProtect against malicious package substitution:\n- Verify package names and metadata with `npm info ` before installation\n- Be extra careful when copy-pasting installation commands from untrusted sources\n- Check source code repositories and npm registry to confirm package legitimacy\n- Default to being logged out of npm during daily development work\n- Use `--ignore-scripts` when installing packages from unknown sources\n\n### Follow Responsible Disclosure\n\nHandle security vulnerabilities appropriately:\n- Follow responsible disclosure programs when reporting vulnerabilities\n- Coordinate with package maintainers before public disclosure\n- Allow time for fixes and upgrade paths before publicizing security issues\n- Use proper channels to report security concerns to package authors\n\n### Package Naming Best Practices\n\nUnderstand npm naming rules and security implications:\n- Package names limited to 214 characters, lowercase only\n- Cannot start with dot, underscore, or contain special characters like \"~\\'!()*\"\n- Be aware that typosquatting attacks target popular package names\n- NPM uses spam detection mechanisms for new package publications\n- Reserved names include node_modules and favicon.ico"
},
{
"path": "sources/owasp/codeguard-0-oauth2.md",
"content": "---\ndescription: OAuth 2.0 Security Best Practices\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\n- yaml\nalwaysApply: false\n---\n\n## OAuth 2.0 Security Guidelines\n\nEssential security practices for implementing secure OAuth 2.0 authorization flows and protecting against common attacks.\n\n### Essential Basics\n\nPrevent open redirectors that can enable token exfiltration:\n- Clients and Authorization Servers must not expose URLs that forward the user's browser to arbitrary URIs obtained from query parameters\n- Use exact string matching for redirect URI validation during client registration\n\nUse proper CSRF protection:\n- When Authorization Server supports PKCE, clients may rely on PKCE's CSRF protection\n- In OpenID Connect flows, the \"nonce\" parameter provides CSRF protection\n- Otherwise, use one-time CSRF tokens in the \"state\" parameter that are securely bound to the user agent\n\nPrevent mix-up attacks in multi-Authorization Server environments:\n- Use the issuer \"iss\" parameter as a countermeasure when interacting with multiple Authorization Servers\n- Alternatively, use distinct redirect URIs to identify different authorization and token endpoints\n- Authorization Servers should avoid accidentally forwarding requests containing user credentials\n\n### PKCE - Proof Key for Code Exchange\n\nPKCE mitigates authorization code interception attacks, especially for public clients:\n\n- Use PKCE flow to prevent injection (replay) of authorization codes into authorization responses\n- Use PKCE code challenge methods that do not expose the verifier in the authorization request\n- Use S256 as the code challenge method instead of plain text\n- Authorization servers must support PKCE and enforce correct \"code_verifier\" usage at the token endpoint\n- Prevent PKCE downgrade attacks by accepting \"code_verifier\" only when \"code_challenge\" was present in the authorization request\n\n### Authorization Code vs Implicit Grant\n\nPrefer Authorization Code Grant over Implicit Grant:\n- Use response type \"code\" (authorization code grant) or \"code id_token\" instead of implicit flows\n- This allows the Authorization Server to detect replay attempts and reduces attack surface\n- Access tokens are not exposed in URLs and can be sender-constrained\n\n### Token Replay Prevention\n\nImplement sender-constraining mechanisms:\n- Use Mutual TLS for OAuth 2.0 or OAuth Demonstration of Proof of Possession (DPoP) to prevent token replays\n- Implement refresh token rotation or ensure refresh tokens are sender-constrained\n\n### Access Token Privilege Restriction\n\nApply the principle of least privilege:\n- Restrict token privileges to the minimum required for the particular application or use case\n- Implement audience restriction by associating access tokens with specific Resource Servers\n- Resource Servers must verify that tokens were intended for their use\n- Restrict tokens to specific resources and actions using \"scope\" and \"authorization_details\" parameters\n- Use \"scope\" and \"resource\" parameters to determine the intended Resource Server\n\n### Avoid Insecure Grant Types\n\nNever use Resource Owner Password Credentials Grant:\n- This grant type insecurely exposes Resource Owner credentials to the client\n- Increases the attack surface of the application\n\n### Client Authentication\n\nUse strong authentication methods:\n- Implement client authentication whenever possible\n- Prefer asymmetric (public-key based) methods like mTLS or \"private_key_jwt\" (OpenID Connect)\n- Asymmetric methods eliminate the need to store sensitive symmetric keys on Authorization Servers\n- This approach is more robust against various attacks\n\n### Additional Security Controls\n\nProtect sensitive claims and enforce secure communications:\n- Authorization Servers must not allow clients to influence their \"client_id\" or \"sub\" values\n- Prevent clients from controlling any claims that could be confused with genuine Resource Owner data\n- Use end-to-end TLS for all communications\n- Never transmit authorization responses over unencrypted network connections\n- Prohibit redirect URIs using \"http\" scheme except for native clients using Loopback Interface Redirection\n\n### Implementation Summary\n\nSecure OAuth 2.0 implementations require:\n- PKCE implementation for all public clients\n- Proper CSRF protection through state parameters or nonce\n- Authorization Code Grant preference over Implicit Grant\n- Token sender-constraining mechanisms (mTLS or DPoP)\n- Strict privilege restriction and audience validation\n- Strong client authentication using asymmetric methods\n- Elimination of insecure grant types\n- Comprehensive TLS enforcement and redirect URI validation\n\nFollowing these practices ensures robust protection against authorization code interception, token replay, privilege escalation, and mix-up attacks while maintaining the flexibility and security benefits of OAuth 2.0."
},
{
"path": "sources/owasp/codeguard-0-open-redirect.md",
"content": "---\ndescription: Open Redirect Prevention - Secure handling of user-controlled redirects\n to prevent phishing attacks\nlanguages:\n- c\n- javascript\n- php\n- typescript\n- vlang\nalwaysApply: false\n---\n\n# Avoid Open Redirects\n\n- Never use user input directly as a redirect target (e.g., `res.redirect(userInput)` in Node.js/Express).\n- If redirection is controlled by user input:\n - Allow only local paths (must start with `/` and not contain protocols like `http:`).\n - OR: Allow only destinations present in a strict allowlist of trusted domains.\n- URLs must be parsed and validated using robust libraries, not simple substring checks.\n- DO NOT allow wildcard domains like `*.example.com` in any allowlist.\n- Add explicit code comments when using redirects to document how the rule is being enforced."
},
{
"path": "sources/owasp/codeguard-0-os-command-injection-defense.md",
"content": "---\ndescription: OS Command Injection Defense\nlanguages:\n- c\n- go\n- java\n- javascript\n- perl\n- php\n- python\n- ruby\n- shell\nalwaysApply: false\n---\n\n## OS Command Injection Defense Guidelines\n\nEssential practices for preventing OS command injection vulnerabilities when executing system commands in applications.\n\n### Understanding Command Injection\n\nCommand injection occurs when software constructs a system command using externally influenced input without properly neutralizing special elements that can modify the intended command.\n\nExample of vulnerable input:\n```\ncalc & echo \"test\"\n```\n\nThis changes the meaning from executing just `calc` to executing both `calc` and `echo \"test\"`.\n\n#### Argument Injection\n\nEvery OS Command Injection is also an Argument Injection, where user input can be passed as arguments while executing a specific command. For example:\n\n```php\nsystem(\"curl \" . escape(\"--help\"))\n```\n\nEven with escaping, this shows the output of `curl --help` instead of the intended behavior.\n\n### Primary Defenses\n\n#### Defense Option 1: Avoid Calling OS Commands Directly\n\nThe primary defense is to avoid calling OS commands directly. Built-in library functions are preferred as they cannot be manipulated to perform unintended tasks.\n\nExample: Use `mkdir()` instead of `system(\"mkdir /dir_name\")`.\n\n#### Defense Option 2: Escape Values Added to OS Commands\n\nUse language-specific escaping functions when OS commands cannot be avoided.\n\nPHP example using escapeshellarg():\nThe `escapeshellarg()` function surrounds user input in single quotes, so malformed input like `& echo \"hello\"` becomes `calc '& echo \"hello\"'` which is parsed as a single argument.\n\nNote: Even with `escapeshellarg()`, an attacker can still pass a single argument to the command.\n\n#### Defense Option 3: Parameterization with Input Validation\n\nIf system commands incorporating user input cannot be avoided, use two layers of defense:\n\nLayer 1 - Parameterization:\nUse structured mechanisms that automatically enforce separation between data and command, providing proper quoting and encoding.\n\nLayer 2 - Input Validation:\n- Commands: Validate against a list of allowed commands\n- Arguments: Use positive/allowlist input validation where arguments are explicitly defined\n- Allowlist Regular Expression: Define allowed characters and maximum length, excluding metacharacters\n\nExample regex allowing only lowercase letters and numbers (3-10 characters): `^[a-z0-9]{3,10}$`\n\nPOSIX Guideline: Use `--` delimiter to prevent argument injection:\n```\ncurl -- $url\n```\nThis prevents argument injection even if `$url` contains additional arguments.\n\nDangerous metacharacters to avoid:\n```\n& | ; $ > < ` \\ ! ' \" ( )\n```\n\n### Code Examples\n\n#### Java\n\nUse ProcessBuilder with separated command and arguments:\n\nIncorrect usage:\n```java\nProcessBuilder b = new ProcessBuilder(\"C:\\DoStuff.exe -arg1 -arg2\");\n```\n\nCorrect usage:\n```java\nProcessBuilder pb = new ProcessBuilder(\"TrustedCmd\", \"TrustedArg1\", \"TrustedArg2\");\n\nMap env = pb.environment();\n\npb.directory(new File(\"TrustedDir\"));\n\nProcess p = pb.start();\n```\n\nNote about Runtime.exec:\nJava's `Runtime.exec` does NOT invoke the shell and does not support shell metacharacters. It splits strings into arrays and executes the first word with the rest as parameters, making shell-based attacks ineffective.\n\n\n#### PHP\n\nUse escapeshellarg() or escapeshellcmd() rather than exec(), system(), or passthru().\n\n### Additional Defenses\n\nImplement defense in depth:\n- Applications should run with the lowest privileges required for necessary tasks\n- Create isolated accounts with limited privileges for single tasks\n\n### Implementation Summary\n\nSecure command execution requires:\n- Avoiding OS commands when possible (use built-in libraries)\n- Using parameterized execution with separated commands and arguments\n- Implementing strict input validation with allowlists\n- Applying proper escaping functions when available\n- Running applications with minimal privileges\n- Using structured mechanisms that enforce data/command separation\n\nFollowing these practices significantly reduces the risk of OS command injection vulnerabilities in applications."
},
{
"path": "sources/owasp/codeguard-0-password-storage.md",
"content": "---\ndescription: Password Storage Security\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\nalwaysApply: false\n---\n\n## Password Storage Security Guidelines\n\nEssential practices for securely storing passwords using modern hashing algorithms to protect against offline attacks.\n\n### Core Principles\n\nPasswords must be hashed, NOT encrypted. Hashing is a one-way function that prevents retrieval of the original password even if the database is compromised. Encryption is reversible and should only be used in rare edge cases where the original password must be recovered.\n\nStrong passwords stored with modern hashing algorithms and proper configuration should be effectively impossible for attackers to crack.\n\nTo sum up our recommendations:\n\n- **Use [Argon2id](#argon2id) with a minimum configuration of 19 MiB of memory, an iteration count of 2, and 1 degree of parallelism.**\n- **If [Argon2id](#argon2id) is not available, use [scrypt](#scrypt) with a minimum CPU/memory cost parameter of (2^17), a minimum block size of 8 (1024 bytes), and a parallelization parameter of 1.**\n- **For legacy systems using [bcrypt](#bcrypt), use a work factor of 10 or more and with a password limit of 72 bytes.**\n- **If FIPS-140 compliance is required, use [PBKDF2](#pbkdf2) with a work factor of 600,000 or more and set with an internal hash function of HMAC-SHA-256.**\n- **Consider using a [pepper](#peppering) to provide additional defense in depth (though alone, it provides no additional secure characteristics).**\n\n### Recommended Algorithms and Parameters\n\nUse these algorithms in order of preference:\n\n#### Argon2id (Preferred)\nArgon2id was the winner of the 2015 Password Hashing Competition and provides balanced resistance to side-channel and GPU-based attacks.\n\nConfiguration options (choose one):\n- m=47104 (46 MiB), t=1, p=1\n- m=19456 (19 MiB), t=2, p=1 \n- m=12288 (12 MiB), t=3, p=1\n- m=9216 (9 MiB), t=4, p=1\n- m=7168 (7 MiB), t=5, p=1\n\nAll configurations provide equal security with different CPU/RAM trade-offs.\n\n#### scrypt (If Argon2id unavailable)\nConfiguration options (choose one):\n- N=2^17 (128 MiB), r=8 (1024 bytes), p=1\n- N=2^16 (64 MiB), r=8 (1024 bytes), p=2\n- N=2^15 (32 MiB), r=8 (1024 bytes), p=3\n- N=2^14 (16 MiB), r=8 (1024 bytes), p=5\n- N=2^13 (8 MiB), r=8 (1024 bytes), p=10\n\n#### bcrypt (Legacy systems only)\nUse work factor of 10 or more. Maximum password length is 72 bytes for most implementations.\n\n#### PBKDF2 (FIPS-140 compliance required)\n- PBKDF2-HMAC-SHA1: 1,300,000 iterations\n- PBKDF2-HMAC-SHA256: 600,000 iterations\n- PBKDF2-HMAC-SHA512: 210,000 iterations\n\n### Salting\n\nModern hashing algorithms (Argon2id, bcrypt, scrypt, PBKDF2) automatically handle salting. Salts must be:\n- Unique for every password\n- Generated using a cryptographically secure random number generator\n- Stored alongside the hash\n\nNever manually implement salting when using modern algorithms.\n\n### Peppering (Optional Defense in Depth)\n\nA pepper is a secret value shared between stored passwords, unlike salts which are unique per password. Peppers provide additional protection if the database is compromised but the application server remains secure.\n\nRequirements for peppering:\n- Store pepper separately from the password database\n- Use secure storage (secrets vaults, HSMs)\n- Generate securely using cryptographically strong methods\n- Changing pepper requires all users to reset passwords\n\nImplementation strategies:\n- Pre-hashing: Add pepper to password before hashing\n- Post-hashing: HMAC the password hash with pepper as key\n\n### Work Factor Tuning\n\nBalance security and performance by adjusting work factors:\n- Target less than one second for hash calculation\n- Increase work factors over time as hardware improves\n- Test on your specific server hardware\n- Higher work factors slow down both legitimate authentication and attacker cracking\n\n### Upgrading Legacy Hashes\n\nFor applications using weak algorithms (MD5, SHA-1):\n\nMethod 1: Force password reset\n- Expire old hashes for inactive users\n- Require password reset on next login\n- More secure but less user-friendly\n\nMethod 2: Layer hashing\n- Use existing hash as input to secure algorithm\n- Example: `bcrypt(md5($password))`\n- Upgrade to direct hashing when user next authenticates\n- Store algorithm and parameters using PHC string format\n\n### bcrypt Pre-Hashing Considerations\n\nIf pre-hashing with bcrypt is necessary:\n- Use `bcrypt(base64(hmac-sha384(data:$password, key:$pepper)), $salt, $cost)`\n- Store pepper outside database\n- Avoid simple pre-hashing like `bcrypt(sha512($password))` due to password shucking vulnerability\n\n### International Character Support\n\nPassword hashing libraries must:\n- Accept full Unicode character range\n- Support null bytes in passwords\n- Preserve entropy without reduction\n- Handle characters from various languages and pictograms\n\n### Performance Guidelines\n\n- Hash calculation should take less than one second\n- Benchmark on production hardware\n- Monitor authentication performance\n- Adjust parameters based on server capacity and user load\n- Consider denial of service risks from overly high work factors\n\n### Implementation Summary\n\nSecure password storage requires:\n- Modern slow hashing algorithms (Argon2id preferred)\n- Proper algorithm configuration with adequate work factors\n- Automatic salt handling by the hashing library\n- Optional pepper for defense in depth\n- Upgrade path for legacy hashes\n- Performance tuning for your environment\n- Support for international characters\n\nFollowing these practices protects user passwords against offline attacks even if the database is compromised."
},
{
"path": "sources/owasp/codeguard-0-php-configuration.md",
"content": "---\ndescription: PHP Secure Configuration\nlanguages:\n- php\nalwaysApply: false\n---\n\n## PHP Secure Configuration Guidelines\n\nEssential security settings for PHP configuration to harden PHP applications against common vulnerabilities.\n\n### PHP Version Management\n\nRun a supported version of PHP. As of this writing, 8.1 is the oldest version receiving security support from PHP, though distribution vendors often provide extended support.\n\n### Error Handling Configuration\n\nConfigure proper error handling to prevent information disclosure while ensuring errors are logged:\n\n```ini\nexpose_php = Off\nerror_reporting = E_ALL\ndisplay_errors = Off\ndisplay_startup_errors = Off\nlog_errors = On\nerror_log = /valid_path/PHP-logs/php_error.log\nignore_repeated_errors = Off\n```\n\nKeep `display_errors` to `Off` on production servers and monitor the logs frequently.\n\n### General Security Settings\n\n```ini\ndoc_root = /path/DocumentRoot/PHP-scripts/\nopen_basedir = /path/DocumentRoot/PHP-scripts/\ninclude_path = /path/PHP-pear/\nextension_dir = /path/PHP-extensions/\nmime_magic.magicfile = /path/PHP-magic.mime\nallow_url_fopen = Off\nallow_url_include = Off\nvariables_order = \"GPCS\"\nallow_webdav_methods = Off\nsession.gc_maxlifetime = 600\n```\n\n`allow_url_*` prevents LFIs from being easily escalated to RFIs.\n\n### File Upload Handling\n\n```ini\nfile_uploads = On\nupload_tmp_dir = /path/PHP-uploads/\nupload_max_filesize = 2M\nmax_file_uploads = 2\n```\n\nIf your application is not using file uploads, `file_uploads` should be turned `Off`.\n\n### Executable Handling\n\n```ini\nenable_dl = Off\ndisable_functions = system, exec, shell_exec, passthru, phpinfo, show_source, highlight_file, popen, proc_open, fopen_with_path, dbmopen, dbase_open, putenv, move_uploaded_file, chdir, mkdir, rmdir, chmod, rename, filepro, filepro_rowcount, filepro_retrieve, posix_mkfifo\ndisable_classes =\n```\n\nThese are dangerous PHP functions. Disable all functions that you don't use.\n\n### Session Handling\n\nSession settings are some of the most important values to concentrate on in configuring. It is a good practice to change `session.name` to something new.\n\n```ini\nsession.save_path = /path/PHP-session/\nsession.name = myPHPSESSID\nsession.auto_start = Off\nsession.use_trans_sid = 0\nsession.cookie_domain = full.qualified.domain.name\n#session.cookie_path = /application/path/\nsession.use_strict_mode = 1\nsession.use_cookies = 1\nsession.use_only_cookies = 1\nsession.cookie_lifetime = 14400 # 4 hours\nsession.cookie_secure = 1\nsession.cookie_httponly = 1\nsession.cookie_samesite = Strict\nsession.cache_expire = 30\nsession.sid_length = 256\nsession.sid_bits_per_character = 6\n```\n\n### Additional Security Settings\n\n```ini\nsession.referer_check = /application/path\nmemory_limit = 50M\npost_max_size = 20M\nmax_execution_time = 60\nreport_memleaks = On\nhtml_errors = Off\nzend.exception_ignore_args = On\n```\n\n### Advanced Protection with Snuffleupagus\n\nSnuffleupagus is the spiritual descendant of Suhosin for PHP 7 and onwards, with modern features. It's considered stable and is usable in production.\n\n### Implementation Summary\n\nSecure PHP configuration requires:\n- Hiding PHP version information (expose_php = Off)\n- Proper error handling with logging enabled but display disabled in production\n- Disabling remote file access (allow_url_fopen/include = Off)\n- Restricting dangerous functions based on application needs\n- Hardening session management with secure cookie settings\n- Setting appropriate resource limits to prevent DoS\n- Using modern security extensions like Snuffleupagus\n\nFollowing these configuration practices significantly reduces the attack surface of PHP applications and protects against common vulnerabilities."
},
{
"path": "sources/owasp/codeguard-0-pinning.md",
"content": "---\ndescription: Certificate and Public Key Pinning Security\nlanguages:\n- c\n- java\n- javascript\n- kotlin\n- matlab\n- swift\n- typescript\n- xml\nalwaysApply: false\n---\n\n## Certificate and Public Key Pinning Guidelines\n\nEssential practices for implementing certificate and public key pinning to prevent Man-in-the-Middle attacks in hostile environments.\n\n### Understanding the Problem\n\nTLS channels can be vulnerable to MITM attacks when certificate-based trust is compromised through:\n1. Attackers acquiring rogue certificates from trusted CAs for victim sites\n2. Attackers injecting dangerous CAs into client trust stores\n\nPinning associates a host with its expected X509 certificate or public key, creating a pinset that advertised credentials must match.\n\n### When NOT to Pin (Critical Decision Criteria)\n\nAvoid pinning in these situations:\n- You don't control both client and server sides of the connection\n- You cannot update the pinset securely without app redeployment\n- Certificate key pairs cannot be predicted before being put into service\n- Application is not a native mobile application\n- Updating pinset is disruptive to operations\n\nThe risk of outages almost always outweighs security benefits given modern certificate authority security advancements.\n\n### When Pinning May Be Appropriate\n\nConsider pinning only when:\n- You control both endpoints and can manage certificate lifecycles\n- You can implement secure pin update mechanisms\n- Your threat model specifically requires protection against CA compromise\n- You have tested thoroughly and planned for certificate rotation\n\n### Implementation Approaches by Platform\n\n#### Android\nUse Android's Network Security Configuration feature with `` configuration settings. Alternatively, use established libraries like OkHTTP for programmatic pinning. Avoid implementing custom SSL validation from scratch.\n\n#### iOS\nApple suggests pinning CA public keys via `Info.plist` under App Transport Security Settings. Use TrustKit library for easier implementation. Custom implementation requires SecTrustEvaluate logic following HTTPS Server Trust Evaluation guidelines.\n\n#### .Net\nImplement using ServicePointManager callbacks for certificate validation.\n\n#### OpenSSL\nUse verify_callback or post-connection validation via SSL_get_peer_certificate. Must call SSL_get_verify_result (verify X509_V_OK) and SSL_get_peer_certificate (verify non-NULL). Fail connection and tear down socket on validation errors.\n\n#### Electron\nUse electron-ssl-pinning library or ses.setCertificateVerifyProc for custom certificate validation.\n\n### What to Pin\n\nPin selection strategy:\n1. Leaf certificate pinning (recommended): Provides 100% certainty but requires backup pins for intermediate CAs to prevent app breakage during certificate rotation\n2. Intermediate CA pinning: Reduces risk but trusts all certificates issued by that CA\n3. Root CA pinning: Not recommended due to high risk from trusting all intermediate CAs\n\nPin type options:\n- Whole certificate: Easiest to implement but requires frequent updates for certificate rotation\n- Public key (subjectPublicKeyInfo): More flexible, allows certificate renewal with same key, provides access to key parameters and algorithm context\n- Hash: Convenient and fixed-length but lacks contextual information\n\nPrefer subjectPublicKeyInfo pinning for balance of flexibility and security context.\n\n### Pin Management Best Practices\n\n#### Pin Addition Timing\nAdd pins at development time (preloading) rather than Trust On First Use (TOFU). Preloading out-of-band prevents attackers from tainting pins.\n\n#### Backup Strategy\nAlways include backup pins (intermediate CA or alternate certificates) to prevent application outages during certificate updates.\n\n#### Update Mechanisms\nPlan secure pin update methods that don't require app redeployment. Consider remote configuration with authenticated channels.\n\n#### Failure Handling\nNever allow users to bypass pin validation failures. Log failures client-side but terminate connections on pin mismatches.\n\n### Corporate Environment Considerations\n\nFor organizations using interception proxies as part of Data Loss Prevention:\n- Do not automatically allow-list interception proxies\n- Add proxy public keys to pinset only after explicit risk acceptance approval\n- Treat corporate proxies as \"good bad actors\" that still break end-to-end security\n\n### Testing and Validation\n\nThoroughly test pinning implementations using OWASP Mobile Security Testing Guide network communication guidelines:\n- Verify pin validation occurs correctly\n- Test certificate rotation scenarios\n- Validate failure handling paths\n- Ensure backup pins function properly\n\n### Operational Considerations\n\n#### Certificate Lifecycle Management\n- Coordinate with backend teams on certificate rotation schedules\n- Plan pin updates in advance of certificate expiration\n- Monitor certificate validity periods\n- Implement alerts for approaching pin expiration\n\n#### Risk Assessment\nUnderstand that pinning creates operational risk of application outages if not managed properly. The security benefit must outweigh availability risks for your specific threat model.\n\n### Common Implementation Errors to Avoid\n\n- Custom TLS or pinning implementations instead of vetted libraries\n- Pinning without backup strategies\n- Allowing user bypass of pin failures\n- Inadequate testing of certificate rotation scenarios\n- Pinning root CAs without understanding the expanded trust implications\n\n### Summary\n\nCertificate and public key pinning can provide additional protection against sophisticated MITM attacks but introduces significant operational complexity and availability risks. Most applications should rely on standard certificate validation rather than implementing pinning. When pinning is necessary, use platform-native solutions or well-established libraries, implement comprehensive backup strategies, and thoroughly test all scenarios including certificate rotation."
},
{
"path": "sources/owasp/codeguard-0-prototype-pollution-prevention.md",
"content": "---\ndescription: Prototype Pollution Prevention\nlanguages:\n- javascript\n- typescript\nalwaysApply: false\n---\n\n# Prototype Pollution Prevention Guideline\n\n## Explanation\n\nPrototype Pollution is a critical vulnerability that can allow attackers to manipulate an application's JavaScript objects and properties, leading to serious security issues such as unauthorized access to data, privilege escalation, and even remote code execution.\n\n## Suggested protection mechanisms\n\n### Use \"new Set()\" or \"new Map()\"\n\nDevelopers should use `new Set()` or `new Map()` instead of using object literals:\n\n```javascript\nlet allowedTags = new Set();\nallowedTags.add('b');\nif(allowedTags.has('b')){\n //...\n}\n\nlet options = new Map();\noptions.set('spaces', 1);\nlet spaces = options.get('spaces')\n```\n\n### If objects or object literals are required\n\nIf objects have to be used then they should be created using the `Object.create(null)` API to ensure they don't inherit from the Object prototype:\n\n```javascript\nlet obj = Object.create(null);\n```\n\nIf object literals are required then as a last resort you could use the `__proto__` property:\n\n```javascript\nlet obj = {__proto__:null};\n```\n\n### Use object \"freeze\" and \"seal\" mechanisms\n\nYou can also use the `Object.freeze()` and `Object.seal()` APIs to prevent built-in prototypes from being modified however this can break the application if the libraries they use modify the built-in prototypes.\n\n### Node.js configuration flag\n\nNode.js also offers the ability to remove the `__proto__` property completely using the `--disable-proto=delete` flag. Note this is a defense in depth measure.\n\nPrototype pollution is still possible using `constructor.prototype` properties but removing `__proto__` helps reduce attack surface and prevent certain attacks.\n\n### Other resources\n\n- [What is prototype pollution? (Portswigger Web Security Academy)](https://portswigger.net/web-security/prototype-pollution)\n- [Prototype pollution (Snyk Learn)](https://learn.snyk.io/lessons/prototype-pollution/javascript/)\n\n### Credits\n\nCredit to [Gareth Hayes](https://garethheyes.co.uk/) for providing the original protection guidance [in this comment](https://github.com/OWASP/ASVS/issues/1563#issuecomment-1470027723)."
},
{
"path": "sources/owasp/codeguard-0-query-parameterization.md",
"content": "---\ndescription: SQL Injection Prevention via Query Parameterization\nlanguages:\n- c\n- java\n- perl\n- php\n- ruby\n- rust\n- sql\nalwaysApply: false\n---\n\n## Query Parameterization Guidelines\n\nEssential practices for preventing SQL injection attacks by using parameterized queries instead of string concatenation when building database queries.\n\n### Core Principle\n\nSQL injection is prevented through parameterized queries that separate SQL structure from data. User input is treated as data parameters, not executable SQL code, preventing attackers from altering query structure.\n\n### Implementation Requirements\n\nAlways use language-specific parameterized queries or prepared statements:\n\n#### Java with PreparedStatement\n```java\nString custname = request.getParameter(\"customerName\");\nString query = \"SELECT account_balance FROM user_data WHERE user_name = ? \"; \nPreparedStatement pstmt = connection.prepareStatement( query );\npstmt.setString( 1, custname);\nResultSet results = pstmt.executeQuery( );\n```\n\n#### Java with Hibernate\n```java\n// HQL\n@Entity // declare as entity;\n@NamedQuery(\n name=\"findByDescription\",\n query=\"FROM Inventory i WHERE i.productDescription = :productDescription\"\n)\npublic class Inventory implements Serializable {\n @Id\n private long id;\n private String productDescription;\n}\n\n// Use case\n// This should REALLY be validated too\nString userSuppliedParameter = request.getParameter(\"Product-Description\");\n// Perform input validation to detect attacks\nList list =\n session.getNamedQuery(\"findByDescription\")\n .setParameter(\"productDescription\", userSuppliedParameter).list();\n\n// Criteria API\n// This should REALLY be validated too\nString userSuppliedParameter = request.getParameter(\"Product-Description\");\n// Perform input validation to detect attacks\nInventory inv = (Inventory) session.createCriteria(Inventory.class).add\n(Restrictions.eq(\"productDescription\", userSuppliedParameter)).uniqueResult();\n```\n\n#### .NET with OleDbCommand\n```csharp\nString query = \"SELECT account_balance FROM user_data WHERE user_name = ?\";\ntry {\n OleDbCommand command = new OleDbCommand(query, connection);\n command.Parameters.Add(new OleDbParameter(\"customerName\", CustomerName Name.Text));\n OleDbDataReader reader = command.ExecuteReader();\n // …\n} catch (OleDbException se) {\n // error handling\n}\n```\n\n#### ASP.NET with SqlCommand\n```csharp\nstring sql = \"SELECT * FROM Customers WHERE CustomerId = @CustomerId\";\nSqlCommand command = new SqlCommand(sql);\ncommand.Parameters.Add(new SqlParameter(\"@CustomerId\", System.Data.SqlDbType.Int));\ncommand.Parameters[\"@CustomerId\"].Value = 1;\n```\n\n#### Ruby with ActiveRecord\n```ruby\n## Create\nProject.create!(:name => 'owasp')\n## Read\nProject.all(:conditions => \"name = ?\", name)\nProject.all(:conditions => { :name => name })\nProject.where(\"name = :name\", :name => name)\n## Update\nproject.update_attributes(:name => 'owasp')\n## Delete\nProject.delete(:name => 'name')\n```\n\n#### Ruby Built-in\n```ruby\ninsert_new_user = db.prepare \"INSERT INTO users (name, age, gender) VALUES (?, ? ,?)\"\ninsert_new_user.execute 'aizatto', '20', 'male'\n```\n\n#### PHP with PDO\n```php\n$stmt = $dbh->prepare(\"INSERT INTO REGISTRY (name, value) VALUES (:name, :value)\");\n$stmt->bindParam(':name', $name);\n$stmt->bindParam(':value', $value);\n```\n\n#### Cold Fusion\n```coldfusion\n\n SELECT * FROM #strDatabasePrefix#_courses WHERE intCourseID =\n \n\n```\n\n#### Perl with DBI\n```perl\nmy $sql = \"INSERT INTO foo (bar, baz) VALUES ( ?, ? )\";\nmy $sth = $dbh->prepare( $sql );\n$sth->execute( $bar, $baz );\n```\n\n#### Rust with SQLx\n```rust\n// Input from CLI args but could be anything\nlet username = std::env::args().last().unwrap();\n\n// Using build-in macros (compile time checks)\nlet users = sqlx::query_as!(\n User,\n \"SELECT * FROM users WHERE name = ?\",\n username\n )\n .fetch_all(&pool)\n .await \n .unwrap();\n\n// Using built-in functions\nlet users: Vec = sqlx::query_as::<_, User>(\n \"SELECT * FROM users WHERE name = ?\"\n )\n .bind(&username)\n .fetch_all(&pool)\n .await\n .unwrap();\n```\n\n### Stored Procedure Security\n\n#### Normal Stored Procedures\nParameters are naturally bound without special requirements:\n\n##### Oracle PL/SQL\n```sql\nPROCEDURE SafeGetBalanceQuery(UserID varchar, Dept varchar) AS BEGIN\n SELECT balance FROM accounts_table WHERE user_ID = UserID AND department = Dept;\nEND;\n```\n\n##### SQL Server T-SQL\n```sql\nPROCEDURE SafeGetBalanceQuery(@UserID varchar(20), @Dept varchar(10)) AS BEGIN\n SELECT balance FROM accounts_table WHERE user_ID = @UserID AND department = @Dept\nEND\n```\n\n#### Dynamic SQL in Stored Procedures\nUse bind variables to ensure dynamic SQL treats inputs as data, not code:\n\n##### Oracle with EXECUTE IMMEDIATE\n```sql\nPROCEDURE AnotherSafeGetBalanceQuery(UserID varchar, Dept varchar)\n AS stmt VARCHAR(400); result NUMBER;\nBEGIN\n stmt := 'SELECT balance FROM accounts_table WHERE user_ID = :1\n AND department = :2';\n EXECUTE IMMEDIATE stmt INTO result USING UserID, Dept;\n RETURN result;\nEND;\n```\n\n##### SQL Server with sp_executesql\n```sql\nPROCEDURE SafeGetBalanceQuery(@UserID varchar(20), @Dept varchar(10)) AS BEGIN\n DECLARE @sql VARCHAR(200)\n SELECT @sql = 'SELECT balance FROM accounts_table WHERE '\n + 'user_ID = @UID AND department = @DPT'\n EXEC sp_executesql @sql,\n '@UID VARCHAR(20), @DPT VARCHAR(10)',\n @UID=@UserID, @DPT=@Dept\nEND\n```\n\n### Critical Security Notes\n\n- Ensure parameterization occurs server-side; client-side parameterization libraries may still build unsafe queries through string concatenation\n- Parameterized queries are the primary defense against SQL injection\n- Input validation should focus on business logic requirements, not SQL injection prevention\n- Never concatenate user input directly into SQL query strings\n- Use bind variables for any dynamic SQL construction within stored procedures"
},
{
"path": "sources/owasp/codeguard-0-rest-assessment.md",
"content": "---\ndescription: RESTful Web Service Security Assessment Guidelines\nlanguages:\n- c\n- go\n- java\n- javascript\n- python\n- ruby\n- typescript\n- xml\n- yaml\nalwaysApply: false\n---\n\n## RESTful Web Service Security Assessment Guidelines\n\nEssential practices for security testing and assessment of RESTful web services, focusing on identifying attack surfaces and testing methodologies.\n\n### Understanding REST Security Challenges\n\nRESTful web services present unique security testing challenges:\n\n- Attack surface is not visible through application inspection since client applications often don't utilize all available service functions\n- Parameters may be embedded in URL paths, custom headers, or structured data rather than standard query strings\n- Large parameter sets in JSON/XML structures significantly increase testing complexity\n- Custom authentication mechanisms require reverse engineering and may not work with standard testing tools\n- Lack of formal documentation makes comprehensive testing difficult\n\n### REST Service Characteristics\n\nKey properties that impact security assessment:\n\n- Primary operations use HTTP methods (GET, POST, PUT, DELETE)\n- Non-standard parameter locations including URL segments and custom headers\n- Structured parameters and responses using JSON or XML formats\n- Custom authentication and session management with security tokens\n- Machine-to-machine communication without traditional login sequences\n\n### Attack Surface Discovery\n\n#### Documentation-Based Discovery\n\nObtain service information for comprehensive coverage:\n\n- Formal service descriptions (WSDL 2.0, WADL) when available\n- Developer guides and API documentation\n- Application source code or configuration files\n- Framework configuration files (especially .NET) that may reveal REST service definitions\n\n#### Proxy-Based Request Collection\n\nUse capable proxy tools to collect complete HTTP interactions:\n\n- Capture full requests including headers and body content, not just URLs\n- REST services utilize more than GET parameters requiring complete request analysis\n- Dynamic client-side activation may not provide visible links for inspection\n\n#### Parameter Identification Techniques\n\nAnalyze collected requests to identify non-standard parameters:\n\n- Abnormal HTTP headers often indicate header-based parameters\n- URL segments with repeating patterns (dates, numbers, ID-like strings) suggest URL-embedded parameters\n- URLs without extensions in the final segment, especially when other segments have extensions\n- Highly varying URL segments with many different values indicate parameters rather than physical directories\n- Structured parameter values in JSON, XML, or custom formats\n\n### Parameter Verification Methods\n\nDistinguish between path elements and parameters:\n\n- Set suspected parameter values to invalid inputs\n- Web server returns 404 for invalid path elements\n- Application returns application-level error messages for invalid parameter values\n- This technique helps confirm parameter identification but doesn't work in all cases\n\n### Fuzzing Optimization Strategies\n\nAnalyze collected parameter values to optimize testing:\n\n- Identify valid versus invalid value patterns\n- Focus fuzzing on marginal invalid values (e.g., zero for positive integers)\n- Identify sequences to test beyond current user's allocated range\n- Understand parameter relationships and dependencies\n\n### Authentication Mechanism Handling\n\nAddress custom authentication challenges:\n\n- Reverse engineer custom token-based authentication\n- Ensure fuzzing tools properly emulate authentication mechanisms\n- Account for session management differences in machine-to-machine communication\n- Test authentication bypass and privilege escalation scenarios\n\n### Testing Methodology Best Practices\n\nSystematic approach to REST service assessment:\n\n- Combine documentation review with dynamic analysis\n- Use proxy tools capable of handling complete HTTP transactions\n- Systematically identify and verify parameter locations\n- Optimize fuzzing based on observed parameter patterns\n- Maintain authentication context throughout testing\n- Document discovered endpoints and parameter structures\n\n### Documentation and Formal Descriptions\n\nImprove assessment efficiency through proper documentation:\n\n- Encourage use of formal service descriptions (WADL, WSDL 2.0)\n- Provide comprehensive developer guides for security assessors\n- Document all endpoints, parameters, and expected data formats\n- Include authentication and authorization requirements\n\n### Security Testing Coverage\n\nEnsure comprehensive security assessment:\n\n- Test all HTTP methods supported by each endpoint\n- Validate input handling for all parameter locations (URL, headers, body)\n- Test authentication and authorization mechanisms\n- Assess rate limiting and denial-of-service protections\n- Verify proper error handling and information disclosure prevention\n\nThis assessment methodology helps identify security vulnerabilities in RESTful web services by addressing the unique challenges they present compared to traditional web applications."
},
{
"path": "sources/owasp/codeguard-0-rest-security.md",
"content": "---\ndescription: REST API Security Guidelines\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\n- xml\n- yaml\nalwaysApply: false\n---\n\n## REST API Security Guidelines\n\nEssential security practices for developing secure RESTful web services, covering transport security, authentication, input validation, and proper error handling.\n\n### Core REST Security Principles\n\nREST APIs are stateless - each request must contain all necessary information for processing. State refers to resource state, not session state. Avoid passing client state to backend as this creates replay and impersonation attack vectors.\n\nEach REST endpoint must independently verify authorization for the requested operation on the specific resource.\n\n### HTTPS Requirements\n\nSecure REST services must only provide HTTPS endpoints to protect:\n- Authentication credentials (passwords, API keys, JSON Web Tokens)\n- Data integrity and confidentiality\n- Client authentication of the service\n\nConsider mutually authenticated client-side certificates for highly privileged web services.\n\n### Access Control\n\nNon-public REST services must perform access control at each API endpoint:\n- Take access control decisions locally at REST endpoints to minimize latency\n- Use centralized Identity Provider (IdP) for user authentication that issues access tokens\n- Avoid relying on global session state across distributed services\n\n### JWT Security\n\nWhen using JSON Web Tokens for security tokens:\n\nEssential Requirements:\n- Ensure JWTs are integrity protected by signature or MAC\n- Never allow unsecured JWTs with `{\"alg\":\"none\"}`\n- Prefer signatures over MACs for integrity protection\n- Verify JWT integrity based on local configuration, not JWT header information\n\nStandard Claims Validation:\n- `iss` (issuer): Verify trusted issuer and signing key ownership\n- `aud` (audience): Confirm relying party is in target audience\n- `exp` (expiration): Validate current time is before token expiration\n- `nbf` (not before): Validate current time is after token validity start\n\nToken Revocation:\n- Implement JWT denylist for explicit session termination\n- Submit hash of revoked JWTs to denylist until natural expiration\n\n### API Keys\n\nFor public REST services requiring access control:\n- Require API keys for every request to protected endpoints\n- Return `429 Too Many Requests` for rate limit violations\n- Revoke API keys for usage agreement violations\n- Do not rely exclusively on API keys for sensitive or high-value resources\n\n### HTTP Method Restrictions\n\n- Apply allowlist of permitted HTTP methods (GET, POST, PUT, DELETE)\n- Reject unauthorized methods with `405 Method not allowed`\n- Verify caller authorization for specific HTTP method on resource\n- Be especially careful with Java EE HTTP verb tampering vulnerabilities\n\n### Input Validation\n\nNever trust input parameters or objects:\n- Validate input length, range, format, and type\n- Use strong types (numbers, booleans, dates) for implicit validation\n- Constrain string inputs with regular expressions\n- Reject unexpected or illegal content\n- Define appropriate request size limits, return `413 Request Entity Too Large`\n- Log input validation failures for attack detection\n- Use secure parsers resistant to XXE and similar attacks\n\n### Content Type Validation\n\nRequest Validation:\n- Reject requests with unexpected or missing Content-Type headers (`406 Unacceptable` or `415 Unsupported Media Type`)\n- Allow missing Content-Type only for Content-Length: 0 requests\n- Explicitly define supported content types in framework configurations\n- Ensure XML parser hardening against XXE attacks\n\nResponse Security:\n- Never copy Accept header directly to Content-Type response header\n- Reject requests with unsupported Accept headers (`406 Not Acceptable`)\n- Send intended content type headers matching response body content\n\n### Management Endpoints\n\n- Avoid exposing management endpoints via Internet\n- Require strong authentication (multi-factor) if Internet-accessible\n- Use different HTTP ports, hosts, or network interfaces\n- Restrict access via firewall rules or access control lists\n\n### Error Handling\n\n- Respond with generic error messages\n- Never reveal technical details (call stacks, internal hints) to clients\n- Avoid exposing system information that aids attackers\n\n### Audit Logging\n\n- Write audit logs before and after security-related events\n- Log token validation errors for attack detection\n- Sanitize log data to prevent log injection attacks\n\n### Security Headers\n\nInclude these headers in all API responses:\n\nRequired Headers:\n- `Cache-Control: no-store`: Prevents sensitive information caching\n- `Content-Security-Policy: frame-ancestors 'none'`: Prevents clickjacking\n- `Content-Type`: Specify correct content type to prevent MIME sniffing\n- `Strict-Transport-Security`: Enforce HTTPS-only access\n- `X-Content-Type-Options: nosniff`: Prevent MIME type confusion\n- `X-Frame-Options: DENY`: Additional clickjacking protection\n\n### CORS Configuration\n\n- Disable CORS headers if cross-domain calls are not required\n- Be as specific as possible when setting allowed origins\n- Avoid wildcard origins in production environments\n\n### Sensitive Information Protection\n\nNever include sensitive data in URLs:\n- Use request body or headers for POST/PUT sensitive data\n- Use HTTP headers for GET request sensitive data\n- Avoid query parameters for passwords, tokens, or API keys\n- URLs may be logged by web servers, proxies, and browsers\n\n### HTTP Status Codes\n\nUse semantically appropriate status codes:\n- `200 OK`: Successful operations\n- `201 Created`: Resource creation with Location header\n- `400 Bad Request`: Malformed requests\n- `401 Unauthorized`: Authentication required\n- `403 Forbidden`: Authorization failed\n- `404 Not Found`: Resource not found\n- `405 Method Not Allowed`: HTTP method not supported\n- `406 Not Acceptable`: Unsupported Accept header\n- `413 Payload Too Large`: Request size exceeded\n- `415 Unsupported Media Type`: Unsupported Content-Type\n- `429 Too Many Requests`: Rate limiting triggered\n- `500 Internal Server Error`: Generic server error (no details)\n\n### Implementation Summary\n\nSecure REST API development requires:\n- HTTPS-only endpoints with proper certificate validation\n- Stateless design with per-endpoint authorization\n- Secure JWT handling with proper validation and revocation\n- Comprehensive input validation and content type enforcement\n- Protected management interfaces with strong authentication\n- Generic error responses without information disclosure\n- Complete audit logging with injection prevention\n- Appropriate security headers for defense in depth\n- Careful CORS configuration and sensitive data handling\n- Semantically correct HTTP status codes for proper client behavior"
},
{
"path": "sources/owasp/codeguard-0-ruby-on-rails.md",
"content": "---\ndescription: Ruby on Rails Security Guidelines\nlanguages:\n- c\n- javascript\n- ruby\n- typescript\n- yaml\nalwaysApply: false\n---\n\n## Ruby on Rails Security Guidelines\n\nEssential security practices for developing secure Ruby on Rails applications.\n\n### Command Injection Prevention\n\nAvoid these dangerous methods with user input:\n\n```ruby\neval(\"ruby code here\")\nsystem(\"os command here\")\n`ls -al /` # (backticks contain os command)\nexec(\"os command here\")\nspawn(\"os command here\")\nopen(\"| os command here\")\nProcess.exec(\"os command here\")\nProcess.spawn(\"os command here\")\nIO.binread(\"| os command here\")\nIO.binwrite(\"| os command here\", \"foo\")\nIO.foreach(\"| os command here\") {}\nIO.popen(\"os command here\")\nIO.read(\"| os command here\")\nIO.readlines(\"| os command here\")\nIO.write(\"| os command here\", \"foo\")\n```\n\nUse allowlists and validation when system interaction is necessary.\n\n### SQL Injection Prevention\n\n```ruby\n# DANGEROUS - Injectable\nname = params[:name]\n@projects = Project.where(\"name like '\" + name + \"'\");\n\n# SAFE - Use parameterized queries\n@projects = Project.where(\"name like ?\", \"%#{ActiveRecord::Base.sanitize_sql_like(params[:name])}%\")\n```\n\n### XSS Prevention\n\nRails auto-escapes by default. Avoid bypassing protection:\n\n```ruby\n# DANGEROUS - Do not do this\n<%= raw @product.name %>\n<%== @product.name %>\n<%= @product.name.html_safe %>\n```\n\nUse `sanitize` helper for limited HTML with allowed tags only.\n\n### Session Management\n\nUse database-backed sessions for better security:\n\n```ruby\nProject::Application.config.session_store :active_record_store\n```\n\n### Transport Security\n\nForce HTTPS in production:\n\n```ruby\n# config/environments/production.rb\nconfig.force_ssl = true\n```\n\n### Authentication with Devise\n\n```bash\ngem 'devise'\nrails generate devise:install\n```\n\nConfigure routes:\n\n```ruby\nRails.application.routes.draw do\n authenticate :user do\n resources :something do # these resource require authentication\n ...\n end\n end\n\n devise_for :users # sign-up/-in/out routes\n root to: 'static#home' # no authentication required\nend\n```\n\nPassword complexity with zxcvbn:\n\n```ruby\nclass User < ApplicationRecord\n devise :database_authenticatable,\n # other devise features, then\n :zxcvbnable\nend\n```\n\n```ruby\n# in config/initializers/devise.rb\nDevise.setup do |config|\n config.min_password_score = 4 # complexity score here.\n ...\n```\n\n### Token Authentication\n\n```bash\ngem 'devise_token_auth'\ngem 'omniauth'\n```\n\n```ruby\nmount_devise_token_auth_for 'User', at: 'auth'\n```\n\n### CSRF Protection\n\n```ruby\nclass ApplicationController < ActionController::Base\n protect_from_forgery\n```\n\nToken authentication doesn't require CSRF protection.\n\n### Secure Redirects\n\n```ruby\n# DANGEROUS\nredirect_to params[:url]\n\n# SAFE\nbegin\n if path = URI.parse(params[:url]).path\n redirect_to path\n end\nrescue URI::InvalidURIError\n redirect_to '/'\nend\n```\n\nUse allowlists for multiple redirect targets:\n\n```ruby\nACCEPTABLE_URLS = {\n 'our_app_1' => \"https://www.example_commerce_site.com/checkout\",\n 'our_app_2' => \"https://www.example_user_site.com/change_settings\"\n}\n\ndef redirect\n url = ACCEPTABLE_URLS[\"#{params[:url]}\"]\n redirect_to url if url\nend\n```\n\n### CORS Configuration\n\n```ruby\n# Gemfile\ngem 'rack-cors', :require => 'rack/cors'\n\n# config/application.rb\nmodule Sample\n class Application < Rails::Application\n config.middleware.use Rack::Cors do\n allow do\n origins 'someserver.example.com'\n resource %r{/users/\\d+.json},\n :headers => ['Origin', 'Accept', 'Content-Type'],\n :methods => [:post, :get]\n end\n end\n end\nend\n```\n\n### Security Headers\n\n```ruby\nActionDispatch::Response.default_headers = {\n 'X-Frame-Options' => 'SAMEORIGIN',\n 'X-Content-Type-Options' => 'nosniff',\n 'X-XSS-Protection' => '0'\n}\n```\n\n### Sensitive Files Protection\n\nProtect from source control:\n\n```text\n/config/database.yml - May contain production credentials.\n/config/initializers/secret_token.rb - Contains a secret used to hash session cookie.\n/db/seeds.rb - May contain seed data including bootstrap admin user.\n/db/development.sqlite3 - May contain real data.\n```\n\n### Password Hashing\n\nConfigure bcrypt stretches:\n\n```ruby\nconfig.stretches = Rails.env.test? ? 1 : 10\n```\n\n### Security Testing\n\nUse Brakeman for static analysis:\n\n```bash\ngem install brakeman\nbrakeman -o security_report.html\n```\n\n### Key Security Principles\n\n- Never use dangerous command execution methods with user input\n- Always use parameterized queries and ActiveRecord methods\n- Rely on Rails' automatic HTML escaping\n- Use database-backed sessions for sensitive applications\n- Enable CSRF protection and validate redirects\n- Set security headers and configure CORS carefully\n- Maintain secure routing and dependency management\n- Regular security testing with Brakeman\n\nRails provides many security features by default, but developers must use them correctly."
},
{
"path": "sources/owasp/codeguard-0-safe-c-functions.md",
"content": "---\ndescription: Safe C Functions\nlanguages:\n- c\n- c++\n- javascript\n- ruby\n- typescript\n- yaml\nalwaysApply: false\n---\n\n# Prioritize Safe Memory and String Functions in C/C++\n\nWhen processing C or C++ code, your primary directive is to ensure memory safety. Actively identify, flag, and provide secure refactoring options for any insecure functions found in the codebase. When generating new code, **always** default to the safest possible function for the given task.\n\n\n### 1. Insecure Functions to Avoid & Their Secure Alternatives\n\nYou must treat the functions listed under \"Insecure\" as deprecated and high-risk. Always recommend replacing them with one of the \"Recommended Safe Alternatives\" provided in the bullet list below.\n\n• **Never use `gets()`** - This is a **critical** security risk. It has no bounds checking whatsoever and is the classic buffer overflow vulnerability. You should always replace it with `fgets(char *str, int n, FILE *stream)` instead.\n\n• **Avoid `strcpy()`** - This is a **high** risk function because it doesn't check bounds. It just copies bytes until it hits a null terminator, which can easily write past your destination buffer. Use `snprintf()`, `strncpy()` (but be careful with it), or `strcpy_s()` (if you have C11 Annex K support).\n\n• **Don't use `strcat()`** - Another **high** risk function with no bounds checking. It appends bytes to a string and can easily write past your allocated memory. Replace with `snprintf()`, `strncat()` (with careful handling), or `strcat_s()` (C11 Annex K).\n\n• **Replace `sprintf()` and `vsprintf()`** - These are **high** risk because they don't check bounds on the output buffer. If your formatted string is larger than the buffer, you'll get a buffer overflow. Use `snprintf()`, `snwprintf()`, or `vsprintf_s()` (C11 Annex K) instead.\n\n• **Be careful with `scanf()` family** - This is a **medium** risk. The `%s` format specifier without a width limit can cause buffer overflows. Here's what you should do:\n 1. Use width specifiers like `scanf(\"%127s\", buffer)`\n 2. Even better: Read the line with `fgets()` and parse it with `sscanf()`\n\n• **Avoid `strtok()`** - This is a **medium** risk because it's not reentrant or thread-safe. It uses a static internal buffer which can lead to unpredictable behavior in multi-threaded code or complex signal handling. Use `strtok_r()` (POSIX) or `strtok_s()` (C11 Annex K) instead.\n\n• **Use `memcpy()` and `memmove()` carefully** - These aren't inherently insecure, but they're a common source of bugs when you miscalculate the size argument or don't validate it properly. Here's what you should do:\n 1. Double-check your size calculations\n 2. Prefer `memcpy_s()` (C11 Annex K) when available\n 3. Use `memmove()` if source and destination buffers might overlap\n\n### 2. Actionable Implementation Guidelines\n\n#### For New Code Generation:\n\n- **NEVER** generate code that uses `gets()`, `strcpy()`, `strcat()`, or `sprintf()`.\n\n- **DEFAULT** to `snprintf()` for string formatting and concatenation, as it's often the most flexible and secure option.\n\n- **DEFAULT** to `fgets()` for reading string input from files or standard input.\n\n\n#### For Code Analysis and Refactoring:\n\n1. **Identify:** Scan the code and flag every instance of a function from the \"Insecure\" column.\n\n2. **Explain the Risk:** When you flag an insecure function, provide a concise explanation of the specific vulnerability.\n\n - _Example Explanation:_ `Warning: The 'strcpy' function does not perform bounds checking and can lead to a buffer overflow if the source string is larger than the destination buffer. This is a common security vulnerability.`\n\n3. **Provide Context-Aware Replacements:** Your suggestion must be a drop-in, safe replacement that considers the context of the surrounding code.\n\n\n#### Use Compiler Flags:\n\nEnable these protective compiler flags to catch buffer overflow vulnerabilities at compile time and runtime:\n\n- **Stack Protection:** Use `-fstack-protector-all` or `-fstack-protector-strong` to detect stack buffer overflows\n- **Address Sanitizer:** Use `-fsanitize=address` during development to catch memory errors\n- **Object Size Checking (OSC):** Use `-D_FORTIFY_SOURCE=2` to enable runtime checks for buffer overflows in functions like `strcpy`, `strcat`, `sprintf`, etc. This adds bounds checking to many of the unsafe functions mentioned above\n- **Format String Protection:** Use `-Wformat -Wformat-security` to catch format string vulnerabilities\n\n### 3. Refactoring Examples\n\nYour suggestions should be concrete and actionable.\n\n**Example 1: Replacing `strcpy`**\n\n- **Original Unsafe Code:**\n\n ```\n char destination[64];\n strcpy(destination, source_string);\n ```\n\n- **Your Suggested Refactoring:**\n\n ```\n char destination[64];\n snprintf(destination, sizeof(destination), \"%s\", source_string);\n ```\n\n- **Your Explanation:** `Replaced 'strcpy' with 'snprintf' to ensure that no more than 63 characters plus a null terminator are written to the destination buffer, preventing a potential buffer overflow.`\n\n\n**Example 2: Correcting `strncpy` Usage**\n\nThe `strncpy` function is a common but imperfect replacement. It may not null-terminate the destination buffer. If you must use it or see it used, you must enforce correct handling.\n\n- **Original (Potentially Unsafe) `strncpy`:**\n\n ```\n // This is unsafe if strlen(source) >= 10\n char dest[10];\n strncpy(dest, source, sizeof(dest));\n ```\n\n- **Your Corrected Suggestion:**\n\n ```\n char dest[10];\n strncpy(dest, source, sizeof(dest) - 1);\n dest[sizeof(dest) - 1] = '\\0';\n ```\n\n- **Your Explanation:** `Added an explicit null termination for 'strncpy'. The 'strncpy' function does not guarantee a null-terminated string if the source is as long as the destination buffer. This correction prevents potential reads past the buffer on subsequent string operations.`\n\n\n**Example 3: Securing `scanf`**\n\n- **Original Unsafe Code:**\n\n ```\n char user_name[32];\n printf(\"Enter your name: \");\n scanf(\"%s\", user_name);\n ```\n\n- **Your Suggested Refactoring:**\n\n ```\n char user_name[32];\n printf(\"Enter your name: \");\n if (fgets(user_name, sizeof(user_name), stdin)) {\n // Optional: Remove trailing newline character from fgets\n user_name[strcspn(user_name, \"\\n\")] = 0;\n }\n ```\n\n- **Your Explanation:** `Replaced 'scanf(\"%s\", ...)' with 'fgets()' to read user input. 'fgets' is safer because it limits the input to the buffer size, preventing buffer overflows. The original 'scanf' had no such protection.`\n\nYou must always explain how this rule was applied and why it was applied."
},
{
"path": "sources/owasp/codeguard-0-saml-security.md",
"content": "---\ndescription: SAML Security Guidelines\nlanguages:\n- java\n- javascript\n- python\n- xml\nalwaysApply: false\n---\n\n## SAML Security Guidelines\n\nEssential security practices for implementing Security Assertion Markup Language (SAML) integrations to prevent common vulnerabilities and attacks.\n\n### Transport Security\n\nUse TLS 1.2 or higher for all SAML message transport to guarantee confidentiality and integrity. This protects against eavesdropping, theft of authentication information, bearer token theft, message deletion/modification, and man-in-the-middle attacks.\n\n### Message Integrity and Authentication\n\nDigitally sign SAML messages using certified keys to guarantee message integrity and authentication. This prevents man-in-the-middle attacks, forged assertions, and message modifications.\n\nEncrypt assertions via XMLEnc to prevent disclosure of sensitive attributes after transportation, protecting against theft of user authentication information.\n\n### Protocol Usage Validation\n\nFollow SAML Profile requirements strictly. The AVANTSSAR team identified these required elements:\n\nAuthnRequest Requirements:\n- Must contain unique ID and SP (Service Provider) identifier\n- Request ID must be returned in response via InResponseTo attribute\n\nResponse Requirements:\n- Must contain unique ID, SP identifier, IdP identifier, and digitally signed assertion\n- InResponseTo must match previously sent request ID\n\nAuthentication Assertion Requirements:\n- Must contain ID, client identifier, IdP identifier, and SP identifier\n\n### XML Signature Security\n\nPrevent XML Signature Wrapping attacks:\n\nSchema Validation:\n- Always perform schema validation before using XML for security purposes\n- Use local, trusted copies of schemas for validation\n- Never allow automatic schema downloads from third parties\n- Inspect and harden schemas to disable wildcard or relaxed processing\n\nDigital Signature Validation:\n- For single signing key: use StaticKeySelector with key obtained directly from IdP\n- For multiple signing keys: use X509KeySelector with keys stored in local JKS\n- Ignore KeyInfo elements in documents\n- For heterogeneous documents: implement full PKIX trust model with trusted root certificates\n\nXML Processing Security:\n- Never use getElementsByTagName to select security elements without validation\n- Always use absolute XPath expressions to select elements\n- Use hardened schemas for validation\n\n### Protocol Processing Rules\n\nValidate all required processing steps:\n\nAuthnRequest Processing:\n- Follow all SAML Core (3.4.1.4) processing rules\n- Prevents man-in-the-middle attacks\n\nResponse Processing:\n- Follow all SAML Profiles (4.1.4.3) processing rules\n- Prevents stolen assertions, man-in-the-middle, forged assertions, and browser state exposure\n\n### Binding Implementation Security\n\nHTTP Redirect Binding:\n- Follow SAML Binding (3.4) specifications\n- Properly encode/decode messages\n\nHTTP POST Binding:\n- Follow SAML Binding (3.5) specifications\n- Prevent caching of SAML messages to avoid stolen assertion and replay attacks\n\n### Security Countermeasures\n\nAdditional protection measures:\n\nIP Filtering:\n- Filter by IP address when appropriate\n- Provide separate endpoints for trusted partners\n- Prevents stolen assertions and man-in-the-middle attacks\n\nResponse Lifetimes:\n- Use short lifetimes on SAML responses\n- Prevents stolen assertions and browser state exposure\n\nOneTimeUse:\n- Mark responses as OneTimeUse\n- Prevents browser state exposure and replay attacks\n\n### IdP-Initiated SSO Security\n\nUnsolicited responses are inherently less secure due to lack of CSRF protection. If required:\n\n- Follow SAML Profiles (4.1.5) validation process\n- Validate RelayState URLs against allowlists to prevent open redirects\n- Implement proper replay detection at response or assertion level\n\n### Identity Provider Best Practices\n\n- Validate X.509 certificates for algorithm compatibility and encryption strength\n- Use strong authentication for SAML token generation\n- Validate which IdP mints tokens\n- Use trusted root CAs when possible\n- Synchronize to common Internet time source\n- Define levels of assurance for identity verification\n- Use asymmetric identifiers over personally identifiable information\n- Sign individual assertions or entire response elements\n\n### Service Provider Best Practices\n\n- Validate session state for users\n- Ensure assertions or entire responses are signed\n- Validate signatures are from authorized IdPs\n- Validate IdP certificates for expiration and revocation (CRL/OCSP)\n- Validate NotBefore and NotOnOrAfter timestamps\n- Validate Recipient attributes\n- Exchange assertions only over secure transports\n- Define clear criteria for session management and SAML logout\n- Verify user identities from SAML assertions when possible\n\n### Input Validation\n\nTreat all SAML input as untrusted external data:\n- Perform proper input validation on all SAML providers and consumers\n- Validate all elements and attributes in SAML messages\n- Sanitize any data extracted from SAML assertions before use\n\n### Cryptographic Requirements\n\n- Use strong encryption for all SAML elements\n- Deprecate support for insecure XMLEnc algorithms (e.g., RSA 1.5)\n- Follow latest cryptoanalysis developments\n- Use modern, secure cryptographic algorithms only\n\n### Summary\n\nSecure SAML implementation requires:\n- TLS 1.2+ transport security with message signing and encryption\n- Strict validation of all protocol elements and processing rules\n- Protection against XML signature wrapping via schema validation and secure XML processing\n- Proper binding implementation with caching prevention\n- Security countermeasures including IP filtering, short lifetimes, and OneTimeUse\n- Careful handling of IdP-initiated SSO with CSRF and replay protection\n- Strong certificate validation and session management\n- Comprehensive input validation and modern cryptography\n\nSAML security depends on following specifications exactly and treating all inputs as potentially malicious."
},
{
"path": "sources/owasp/codeguard-0-securing-cascading-style-sheets.md",
"content": "---\ndescription: Securing Cascading Style Sheets\nlanguages:\n- c\n- javascript\n- typescript\nalwaysApply: false\n---\n\n## Securing Cascading Style Sheets\n\nPrevent CSS files from exposing application features, user roles, and sensitive functionality to attackers performing reconnaissance.\n\n### Security Risks\n\n#### Risk 1: Information Disclosure Through CSS Selectors\nMotivated attackers examine CSS files to learn application features before attempting attacks. Global CSS files containing role-based selectors reveal:\n- Different user roles and permissions\n- Available features and functionality\n- Application structure and sensitive endpoints\n\nExample problematic selectors:\n- `.profileSettings`\n- `.addUsers`\n- `.deleteUsers` \n- `.exportUserData`\n- `.addNewAdmin`\n\n#### Risk 2: Descriptive Selector Names\nReadable selector names help attackers map CSS classes to actual application features:\n- `.changePassword`\n- `.oldPassword`\n- `.newPassword`\n- `.confirmNewPassword`\n\n### Defensive Mechanisms\n\n#### Defense 1: Isolate CSS by Access Control Level\n- Create separate CSS files per role (StudentStyling.CSS, AdministratorStyling.CSS)\n- Restrict CSS file access to users with proper access control level only\n- Implement server-side validation before serving CSS files\n- Log and alert on unauthorized CSS file access attempts (forced browsing)\n- Ensure authenticated users cannot access CSS files for other roles\n\n#### Defense 2: Remove Identifying Information\n- Use consistent styling across pages to reduce need for specific selectors\n- Write general CSS rules that apply across multiple pages\n- Create CSS selectors targeting HTML elements without revealing functionality\n\nTransform descriptive selectors:\n```\n// Instead of this revealing selector:\n#UserPage .Toolbar .addUserButton\n\n// Use obscure structural targeting:\n#page_u header button:first-of-type\n```\n\nBuild-time and runtime obfuscation tools:\n- JSS (CSS in JS) with minify option generates class names like `.c001`, `.c002`\n- CSS Modules with modules and localIdentName options for obfuscation\n- .Net Blazor CSS Isolation creates scoped selectors like `button.add[b-3xxtam6d07]`\n- CSS libraries (Bootstrap, Tailwind) reduce need for specific selectors\n\n#### Defense 3: Prevent Malicious CSS in User Content\n- Validate and sanitize user-authored HTML content\n- Restrict CSS styles allowed in user-generated content\n- Prevent uploaded HTML from using styles for unintended purposes\n- Be aware that CSS can be used for clickjacking attacks where clicking anywhere on the page loads malicious websites\n\n### Implementation Guidelines\n\n1. Segment CSS files by user roles and access levels\n2. Implement access control validation before serving CSS resources\n3. Use build-time tools to obfuscate class names and selectors\n4. Prefer structural and element-based selectors over feature-specific names\n5. Leverage CSS frameworks to minimize custom selectors\n6. Sanitize and restrict user-generated HTML content containing styles\n7. Monitor and log unauthorized attempts to access role-specific CSS files\n8. Avoid global CSS files that contain selectors for all user roles\n9. Use generic, non-descriptive class names that don't reveal functionality\n10. Test CSS access controls to ensure proper isolation between roles"
},
{
"path": "sources/owasp/codeguard-0-server-side-request-forgery-prevention.md",
"content": "---\ndescription: Server-Side Request Forgery Prevention\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\nalwaysApply: false\n---\n\n## Server-Side Request Forgery Prevention\n\nPrevent SSRF attacks that abuse applications to interact with internal/external networks by validating and restricting outbound requests.\n\n### SSRF Attack Context\n\nSSRF exploits occur when applications:\n- Process user-provided URLs for external resources (avatars, webhooks)\n- Make internal requests using user-controlled data\n- Handle URL redirections without proper validation\n\nSSRF is not limited to HTTP - attackers can exploit FTP, SMB, SMTP protocols and schemes like `file://`, `phar://`, `gopher://`, `data://`, `dict://`.\n\n### Case 1: Allowlist Approach (Known Trusted Destinations)\n\nWhen applications communicate only with identified trusted applications, use strict allowlisting.\n\n#### Application Layer Protection\n\nAlways disable HTTP redirects in web clients to prevent bypass attempts.\n\n#### String Validation\nUse regex for simple formats, libraries for complex validation:\n\n```java\n//Regex validation for a data having a simple format\nif(Pattern.matches(\"[a-zA-Z0-9\\\\s\\\\-]{1,50}\", userInput)){\n //Continue the processing because the input data is valid\n}else{\n //Stop the processing and reject the request\n}\n```\n\n#### IP Address Validation\nUse battle-tested libraries to validate IP format and prevent encoding bypasses:\n\n- Java: `InetAddressValidator.isValid()` from Apache Commons Validator\n- .NET: `IPAddress.TryParse()` from SDK\n- JavaScript: `ip-address` library \n- Ruby: `IPAddr` class from SDK\n\nCreate allowlist of all trusted application IPs (IPv4 and IPv6). Use output value from validation library for strict string comparison against allowlist.\n\n#### Domain Name Validation\nUse libraries that validate format without DNS resolution:\n\n- Java: `DomainValidator.isValid()` from Apache Commons Validator\n- .NET: `Uri.CheckHostName()` from SDK\n- JavaScript: `is-valid-domain` library\n- Python: `validators.domain` module\n- Ruby: Use regex `^(((?!-))(xn--|_{1,1})?[a-z0-9-]{0,61}[a-z0-9]{1,1}\\.)*(xn--)?([a-z0-9][a-z0-9\\-]{0,60}|[a-z0-9-]{1,30}\\.[a-z]{2,})$`\n\nMonitor allowlisted domains for DNS pinning attacks - alert when domains resolve to local/internal IP addresses.\n\n#### URL Handling\nDo not accept complete URLs from users. URLs are difficult to validate and parsers can be exploited. Accept only validated IP addresses or domain names.\n\n#### Network Layer Protection\n- Use firewalls to restrict application network access to only required destinations\n- Implement network segregation to block illegitimate calls at network level\n- Define legitimate flows and block all others\n\n### Case 2: Dynamic External Destinations (Block-list Approach)\n\nWhen applications must access arbitrary external resources (webhooks), use block-list validation.\n\n#### Validation Flow\n1. Validate input format using libraries from Case 1\n2. For IP addresses: Verify it's public (not private, localhost, or link-local)\n3. For domains: \n - Verify it's external using internal DNS resolver that only resolves internal names\n - Resolve domain to IPs and validate all returned addresses are public\n4. Restrict protocols to HTTP/HTTPS only via allowlist\n5. Require legitimate request proof via secure token\n\n#### Secure Token Requirements\n- Target application generates random 20-character alphanumeric token\n- Token passed as POST parameter with name using only `[a-z]{1,10}` characters\n- Endpoint accepts only HTTP POST requests\n- Build requests using only validated information\n\n#### Example Python Monitoring Script\nMonitor allowlisted domains for DNS pinning:\n\n```python\n# Dependencies: pip install ipaddress dnspython\nimport ipaddress\nimport dns.resolver\n\n# Configure the allowlist to check\nDOMAINS_ALLOWLIST = [\"owasp.org\", \"labslinux\"]\n\n# Configure the DNS resolver to use for all DNS queries\nDNS_RESOLVER = dns.resolver.Resolver()\nDNS_RESOLVER.nameservers = [\"1.1.1.1\"]\n\ndef verify_dns_records(domain, records, type):\n \"\"\"\n Verify if one of the DNS records resolve to a non public IP address.\n Return a boolean indicating if any error has been detected.\n \"\"\"\n error_detected = False\n if records is not None:\n for record in records:\n value = record.to_text().strip()\n try:\n ip = ipaddress.ip_address(value)\n # See https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address.is_global\n if not ip.is_global:\n print(\"[!] DNS record type '%s' for domain name '%s' resolve to a non public IP address '%s'!\" % (type, domain, value))\n error_detected = True\n except ValueError:\n error_detected = True\n print(\"[!] '%s' is not valid IP address!\" % value)\n return error_detected\n\ndef check():\n \"\"\"\n Perform the check of the allowlist of domains.\n Return a boolean indicating if any error has been detected.\n \"\"\"\n error_detected = False\n for domain in DOMAINS_ALLOWLIST:\n # Get the IPs of the current domain\n # See https://en.wikipedia.org/wiki/List_of_DNS_record_types\n try:\n # A = IPv4 address record\n ip_v4_records = DNS_RESOLVER.query(domain, \"A\")\n except Exception as e:\n ip_v4_records = None\n print(\"[i] Cannot get A record for domain '%s': %s\\n\" % (domain,e))\n try:\n # AAAA = IPv6 address record\n ip_v6_records = DNS_RESOLVER.query(domain, \"AAAA\")\n except Exception as e:\n ip_v6_records = None\n print(\"[i] Cannot get AAAA record for domain '%s': %s\\n\" % (domain,e))\n # Verify the IPs obtained\n if verify_dns_records(domain, ip_v4_records, \"A\") or verify_dns_records(domain, ip_v6_records, \"AAAA\"):\n error_detected = True\n return error_detected\n\nif __name__== \"__main__\":\n if check():\n exit(1)\n else:\n exit(0)\n```\n\n### Cloud-Specific Protections\n\n#### AWS IMDSv2\nIn cloud environments, SSRF targets metadata services to steal credentials. Migrate to IMDSv2 and disable IMDSv1 for additional protection against SSRF accessing AWS Instance Metadata Service.\n\n### Essential Implementation Guidelines\n\n1. Never accept raw URLs from users - validate only IP addresses or domain names\n2. Use established libraries for IP/domain validation to prevent encoding bypasses \n3. Implement strict allowlists with case-sensitive exact matching for trusted destinations\n4. Disable HTTP redirects in all outbound HTTP clients\n5. For dynamic destinations, block private/internal IP ranges and validate DNS resolution\n6. Restrict protocols to HTTP/HTTPS only\n7. Require secure tokens for request legitimacy verification\n8. Apply network-layer restrictions via firewalls and segmentation\n9. Monitor allowlisted domains for DNS pinning attacks\n10. Use cloud-specific protections like AWS IMDSv2"
},
{
"path": "sources/owasp/codeguard-0-session-management.md",
"content": "---\ndescription: Session Management Security\nlanguages:\n- c\n- go\n- java\n- javascript\n- kotlin\n- php\n- python\n- ruby\n- scala\n- swift\n- typescript\nalwaysApply: false\n---\n\n## Session Management Security\n\nImplement secure session handling to prevent session hijacking, fixation, and unauthorized access through proper ID generation, cookie security, and lifecycle management.\n\n### Session ID Properties\n\n#### Secure Generation\n- Use cryptographically secure pseudorandom number generator (CSPRNG) for session IDs\n- Ensure minimum 64 bits of entropy (16 hexadecimal characters minimum)\n- Generate completely random, opaque session IDs with no meaningful content\n- Change default session ID names (PHPSESSID, JSESSIONID) to generic names like \"id\"\n\n#### Session ID Content\n- Session IDs must be meaningless identifiers on client side\n- Never include sensitive information or PII in session ID values\n- Store all session data (user details, permissions, state) server-side only\n- Encrypt session storage if it contains sensitive information\n\n### Cookie Security Configuration\n\n#### Essential Cookie Attributes\n- Secure: Only transmit over HTTPS connections\n- HttpOnly: Prevent JavaScript access to protect against XSS\n- SameSite: Use Strict or Lax to mitigate CSRF attacks\n- Domain/Path: Scope cookies narrowly to minimize exposure\n\n#### Cookie Persistence\n- Use non-persistent session cookies (no Expires or Max-Age attributes)\n- Session should disappear when browser instance closes\n- Avoid persistent cookies for session management\n\nExample secure cookie configuration:\n```\nSet-Cookie: id=; Secure; HttpOnly; SameSite=Strict; Path=/app\n```\n\n### Transport Layer Security\n\n- Enforce HTTPS for entire web session, not just authentication\n- Never mix HTTP and HTTPS within same user session\n- Implement HTTP Strict Transport Security (HSTS)\n- Set or regenerate cookies only after HTTPS redirect occurs\n\n### Session Lifecycle Management\n\n#### Session ID Generation and Verification\n- Use strict session management - only accept server-generated session IDs\n- Reject any session ID not previously created by the application\n- Treat session IDs as untrusted user input requiring validation\n- Detect and alert on unknown session IDs as suspicious activity\n\n#### Session ID Regeneration\n- Regenerate session ID after any privilege level change\n- Mandatory regeneration during authentication process\n- Regenerate on password changes, permission changes, role changes\n- Use different session ID names for pre/post authentication states\n- Invalidate previous session IDs when generating new ones\n\nFramework examples for regeneration:\n- J2EE: `request.getSession(true)` & `HttpSession.invalidate()`\n- ASP.NET: `Session.Abandon()` & `Response.Cookies.Add(new...)`\n- PHP: `session_start()` & `session_regenerate_id(true)`\n\n### Session Expiration\n\n#### Automatic Expiration\n- Implement idle timeout (2-5 minutes for high-value, 15-30 minutes for low-risk)\n- Implement absolute timeout (4-8 hours based on application usage)\n- Enforce timeouts server-side, never rely solely on client-side controls\n- Optionally implement renewal timeout to periodically regenerate session IDs\n\n#### Manual Expiration\n- Provide visible, accessible logout button on every page\n- Fully invalidate sessions server-side on logout\n- Clear session cookies client-side with empty value and past expiration\n\nServer-side invalidation examples:\n- J2EE: `HttpSession.invalidate()`\n- ASP.NET: `Session.Abandon()`\n- PHP: `session_destroy()/unset()`\n\n### Web Content Caching Protection\n\n- Use Cache-Control: no-store for responses containing session IDs\n- Apply restrictive cache directives for all sensitive content\n- Prevent session ID caching in browser history or proxy servers\n- Include cache control headers on all pages displaying sensitive data\n\n### Attack Detection and Monitoring\n\n#### Session Attack Detection\n- Monitor for session ID brute force attempts from single IP addresses\n- Detect session ID anomalies and manipulation attempts\n- Log session lifecycle events (creation, renewal, destruction)\n- Bind sessions to client properties (IP, User-Agent) for anomaly detection\n\n#### Logging Best Practices\n- Log session events using salted hash of session ID (not actual ID)\n- Include timestamps, IP addresses, User-Agent, and operation details\n- Monitor for simultaneous sessions and enforce business policies\n- Protect administrative session management interfaces\n\n### Client-Side Storage Security\n\n#### Avoid Insecure Storage\n- Never store session tokens in localStorage or sessionStorage\n- Avoid any JavaScript-accessible session storage due to XSS risk\n- If JavaScript access required, use Web Workers to isolate secrets\n- Prefer HttpOnly cookies for session token exchange\n\n#### Web Workers Alternative\n- Use Web Workers for browser storage when persistence not required\n- Keep secrets within Web Worker context, never transmit to main window\n- Provides similar security guarantees as HttpOnly cookies\n\n### Framework and Implementation\n\n#### Built-in Session Management\n- Prefer established framework session mechanisms over custom solutions\n- Keep frameworks updated to latest versions with security fixes\n- Review and harden default framework configurations\n- Ensure secure session storage repository protection\n\n#### Multiple Cookie Considerations\n- Verify all cookies for sessions using multiple cookies\n- Enforce relationships between pre/post authentication cookies\n- Avoid same cookie names for different paths or domains\n- Prevent cross-subdomain cookie exposure\n\n### Reauthentication Requirements\n\nRequire reauthentication for high-risk events:\n- Password changes\n- Login from new/suspicious IP addresses or devices\n- Account recovery completion\n- Privilege escalation events\n\n### Additional Security Measures\n\n#### Client-Side Defenses (Defense-in-Depth)\n- Implement login timeouts to force session ID renewal\n- Force logout on browser window close events\n- Disable cross-tab session sharing where feasible\n- Automatic client logout with countdown warnings\n\n#### WAF Protection\n- Use Web Application Firewalls to enforce cookie security attributes\n- Implement WAF-based session fixation protection\n- Apply sticky session enforcement via WAF rules\n- Use WAF for session expiration management when code changes limited\n\n### Essential Implementation Checklist\n\n1. Generate session IDs using CSPRNG with minimum 64 bits entropy\n2. Configure cookies with Secure, HttpOnly, SameSite attributes\n3. Enforce HTTPS site-wide with HSTS headers\n4. Regenerate session IDs on all privilege changes\n5. Implement both idle and absolute session timeouts\n6. Provide complete logout functionality with server-side invalidation\n7. Apply no-store cache directives for sensitive content\n8. Monitor session attacks and log security events\n9. Use framework built-in session management\n10. Require reauthentication for sensitive operations"
},
{
"path": "sources/owasp/codeguard-0-sql-injection-prevention.md",
"content": "---\ndescription: SQL Injection Prevention Guidelines\nlanguages:\n- c\n- go\n- java\n- javascript\n- perl\n- php\n- python\n- ruby\n- sql\n- typescript\nalwaysApply: false\n---\n\n## SQL Injection Prevention Guidelines\n\nEssential practices for preventing SQL injection attacks by using secure database query construction methods instead of string concatenation.\n\n### Understanding SQL Injection\n\nSQL injection occurs when applications use dynamic database queries that concatenate user input directly into SQL strings. Attackers can exploit this to execute malicious SQL code. To prevent SQL injection, developers must either stop writing dynamic queries with string concatenation or prevent malicious SQL input from being included in executed queries.\n\n### Primary Defense Options\n\n#### Option 1: Prepared Statements (Parameterized Queries) - Preferred\n\nUse prepared statements with variable binding to separate SQL code from data. The database will always distinguish between code and data, preventing attackers from changing query intent.\n\nSafe Java example:\n```java\n// This should REALLY be validated too\nString custname = request.getParameter(\"customerName\");\n// Perform input validation to detect attacks\nString query = \"SELECT account_balance FROM user_data WHERE user_name = ? \";\nPreparedStatement pstmt = connection.prepareStatement( query );\npstmt.setString( 1, custname);\nResultSet results = pstmt.executeQuery( );\n```\n\nSafe C# .NET example:\n```csharp\nString query = \"SELECT account_balance FROM user_data WHERE user_name = ?\";\ntry {\n OleDbCommand command = new OleDbCommand(query, connection);\n command.Parameters.Add(new OleDbParameter(\"customerName\", CustomerName Name.Text));\n OleDbDataReader reader = command.ExecuteReader();\n // …\n} catch (OleDbException se) {\n // error handling\n}\n```\n\nSafe HQL example:\n```java\n// This is an unsafe HQL statement\nQuery unsafeHQLQuery = session.createQuery(\"from Inventory where productID='\"+userSuppliedParameter+\"'\");\n// Here is a safe version of the same query using named parameters\nQuery safeHQLQuery = session.createQuery(\"from Inventory where productID=:productid\");\nsafeHQLQuery.setParameter(\"productid\", userSuppliedParameter);\n```\n\n#### Option 2: Stored Procedures (When Implemented Safely)\n\nUse stored procedures only if inputs are parameterized and no dynamic SQL generation occurs within them.\n\nSafe Java stored procedure example:\n```java\n// This should REALLY be validated\nString custname = request.getParameter(\"customerName\");\ntry {\n CallableStatement cs = connection.prepareCall(\"{call sp_getAccountBalance(?)}\");\n cs.setString(1, custname);\n ResultSet results = cs.executeQuery();\n // … result set handling\n} catch (SQLException se) {\n // … logging and error handling\n}\n```\n\nSafe VB .NET stored procedure example:\n```vbnet\n Try\n Dim command As SqlCommand = new SqlCommand(\"sp_getAccountBalance\", connection)\n command.CommandType = CommandType.StoredProcedure\n command.Parameters.Add(new SqlParameter(\"@CustomerName\", CustomerName.Text))\n Dim reader As SqlDataReader = command.ExecuteReader()\n '...\n Catch se As SqlException\n 'error handling\n End Try\n```\n\n#### Option 3: Allow-list Input Validation\n\nFor SQL elements that cannot use bind variables (table names, column names, sort indicators), use strict allow-listing.\n\nSafe table name validation:\n```text\nString tableName;\nswitch(PARAM):\n case \"Value1\": tableName = \"fooTable\";\n break;\n case \"Value2\": tableName = \"barTable\";\n break;\n ...\n default : throw new InputValidationException(\"unexpected value provided\"\n + \" for table name\");\n```\n\nSafe dynamic query for sort order:\n```java\npublic String someMethod(boolean sortOrder) {\n String SQLquery = \"some SQL ... order by Salary \" + (sortOrder ? \"ASC\" : \"DESC\");`\n ...\n```\n\n#### Option 4: Escaping (Strongly Discouraged)\n\nEscaping user input is database-specific, error-prone, and cannot guarantee prevention of all SQL injections. Use parameterized queries instead.\n\n### Additional Defenses\n\n#### Least Privilege\n\nMinimize privileges for all database accounts:\n- Grant only necessary access rights (read vs. write)\n- Avoid DBA or admin access for application accounts\n- Use separate database users for different applications\n- Consider using views to limit data access further\n\n#### Input Validation\n\nUse input validation as a secondary defense to detect unauthorized input before SQL execution. Validated data is not necessarily safe for string concatenation - always use parameterized queries.\n\n### Key Principles\n\n- Define all SQL code first, then pass parameters separately\n- Never concatenate user input directly into SQL strings\n- Treat user input as data, never as executable SQL code\n- Use least privilege database accounts\n- Implement input validation as defense in depth, not primary protection"
},
{
"path": "sources/owasp/codeguard-0-symfony.md",
"content": "---\ndescription: Symfony Security Best Practices\nlanguages:\n- php\n- yaml\nalwaysApply: false\n---\n\n## Symfony Security Best Practices\n\nEssential security practices for developing secure Symfony applications, covering common vulnerabilities and framework-specific protections.\n\n### Cross-Site Scripting (XSS) Prevention\n\nUse Twig's default `{{ }}` output escaping for all variables. Only use `|raw` filter for trusted content requiring HTML rendering.\n\n```twig\nHello {{name}}
\n{# if 'name' is '', Twig will output this:\n'Hello <script>alert('hello!')</script>
' #}\n\n{{ product.title|raw }}
\n{# if 'product.title' is 'Lorem Ipsum', Twig will output\nexactly that instead of 'Lorem <strong>Ipsum</strong>' #}\n```\n\n### CSRF Protection\n\nSymfony Forms include CSRF tokens automatically. For manual handling, use `csrf_token()` and `isCsrfTokenValid()`.\n\n```php\nclass PostForm extends AbstractType\n{\n public function configureOptions(OptionsResolver $resolver): void\n {\n $resolver->setDefaults([\n // ... \n 'csrf_protection' => true, // enable/disable csrf protection for this form\n 'csrf_field_name' => '_csrf_token',\n 'csrf_token_id' => 'post_item', // change arbitrary string used to generate\n ]);\n }\n}\n```\n\nManual CSRF token handling:\n```twig\n\n```\n\n```php\nclass ExampleController extends AbstractController\n{\n #[Route('/posts/{id}', methods: ['DELETE'], name: 'delete_post')]\n public function delete(Post $post, Request $request): Response \n { \n $token = $request->request->get('token');\n if($this->isCsrfTokenValid($token)) {\n // ...\n }\n // ...\n }\n}\n```\n\n### SQL Injection Prevention\n\nUse parameterized queries with Doctrine ORM. Never concatenate user input in SQL strings.\n\n```php\n// Repository method\n$post = $em->getRepository(Post::class)->findOneBy(['id' => $id]);\n\n// DQL with parameters\n$query = $em->createQuery(\"SELECT p FROM App\\Entity\\Post p WHERE p.id = :id\");\n$query->setParameter('id', $id);\n$post = $query->getSingleResult();\n\n// DBAL Query Builder\n$qb = $em->createQueryBuilder();\n$post = $qb->select('p')\n ->from('posts','p')\n ->where('id = :id')\n ->setParameter('id', $id)\n ->getQuery()\n ->getSingleResult();\n```\n\n### Command Injection Prevention\n\nAvoid `exec()`, `shell_exec()`, `system()` with user input. Use Symfony Filesystem component or native PHP functions.\n\n```php\n// Vulnerable example\n$filename = $request->request->get('filename');\nexec(sprintf('rm %s', $filename));\n\n// Secure alternatives - use native PHP or Symfony Filesystem\nunlink($filename);\n\n// Or Symfony Filesystem component\nuse Symfony\\Component\\Filesystem\\Filesystem;\n$filesystem = new Filesystem();\n$filesystem->remove($filename);\n```\n\n### File Upload Security\n\nValidate file uploads with Symfony Validator constraints. Store files outside public directory with unique names.\n\n```php\nclass UploadDto\n{\n public function __construct(\n #[File(\n maxSize: '1024k',\n mimeTypes: ['application/pdf', 'application/x-pdf'],\n )]\n public readonly UploadedFile $file,\n ){}\n}\n```\n\n### Directory Traversal Prevention\n\nUse `realpath()` and `basename()` to validate and sanitize file paths.\n\n```php\n$storagePath = $this->getParameter('kernel.project_dir') . '/storage';\n$filePath = $storagePath . '/' . $filename;\n\n$realBase = realpath($storagePath);\n$realPath = realpath($filePath);\n\nif ($realPath === false || !str_starts_with($realPath, $realBase)) {\n //Directory Traversal!\n}\n\n// Alternative: strip directory information\n$filePath = $storagePath . '/' . basename($filename);\n```\n\n### Security Configuration\n\nConfigure session security, authentication, and access controls properly.\n\n```yaml\n# Session configuration\nframework:\n session:\n cookie_httponly: true\n cookie_lifetime: 5\n cookie_samesite: lax\n cookie_secure: auto\n\n# Authentication providers, firewalls, and access control\nsecurity:\n providers:\n app_user_provider:\n entity:\n class: App\\Entity\\User\n property: email\n firewalls:\n dev:\n pattern: ^/(_(profiler|wdt)|css|images|js)/\n security: false\n admin:\n lazy: true\n provider: app_user_provider\n pattern: ^/admin\n custom_authenticator: App\\Security\\AdminAuthenticator\n logout:\n path: app_logout\n target: app_login\n main:\n lazy: true\n provider: app_user_provider\n access_control:\n - { path: ^/admin, roles: ROLE_ADMIN }\n - { path: ^/login, roles: PUBLIC_ACCESS }\n```\n\n### Production Security\n\n- Set `APP_ENV=prod` and disable debug mode\n- Run regular security checks: `composer update` and `symfony check:security`\n- Use Symfony secrets for sensitive data\n- Configure CORS with `nelmio/cors-bundle` (avoid wildcard origins)\n- Implement security headers (HSTS, CSP, X-Frame-Options)\n- Enforce HTTPS and set proper file permissions"
},
{
"path": "sources/owasp/codeguard-0-third-party-javascript-management.md",
"content": "---\ndescription: Third Party JavaScript Management Security\nlanguages:\n- c\n- javascript\n- typescript\nalwaysApply: false\n---\n\n## Third Party JavaScript Management Security\n\nSecure third-party JavaScript tags to prevent arbitrary code execution, data leakage, and loss of application control.\n\n### Major Risks\n\nThird-party JavaScript poses three critical risks:\n1. Loss of control over client application changes\n2. Execution of arbitrary code on client systems\n3. Disclosure of sensitive information to third parties\n\n### Security Strategies\n\n#### Server Direct Data Layer (Recommended)\nCreate controlled data layer that third-party scripts can access instead of direct DOM access.\n\nKey principles:\n- Only first-party code populates the data layer\n- Third-party scripts read exclusively from sanitized data layer\n- Tag JavaScript can only access host data layer values, never URL parameters\n\nBenefits:\n- Only your JavaScript executes on user browsers\n- Only validated data sent to vendors\n- Scalable for large sites with multiple vendor tags\n\n#### Subresource Integrity (SRI)\nEnsure only reviewed code executes by adding integrity metadata.\n\n```html\n\n```\n\nRequirements:\n- Vendor host must have CORS enabled\n- Monitor vendor JavaScript for changes regularly\n- Update integrity hashes when vendor updates scripts\n\n#### Sandboxing with iframe\nIsolate vendor JavaScript to prevent direct DOM and cookie access.\n\n```html\n\n\n \n \n ...\n \n \n \n\n\n\n\n \n \n ...\n \n \n \n \n \n \n```\n\nCommunication requirements:\n- Use postMessage mechanism for secure data exchange\n- Validate event origins before processing messages\n- Consider Content Security Policy (CSP) for additional protection\n\n#### Content Sanitization\nClean DOM data before sending to third parties using:\n- DOMPurify: XSS sanitizer for HTML, MathML and SVG\n- MentalJS: JavaScript parser and sandbox\n\n#### Tag Manager Controls\nFor tag management systems:\n- Restrict JavaScript access to data layer values only\n- Disable custom HTML tags and JavaScript code where possible\n- Verify tag manager security practices and access controls\n- Implement two-factor authentication for tag configuration\n\n### Operational Security\n\n#### Keep Libraries Updated\n- Regularly update JavaScript libraries to address vulnerabilities\n- Use tools like RetireJS to identify vulnerable libraries\n\n#### Vendor Agreements\nContractual controls:\n- Require evidence of secure coding practices and code integrity monitoring\n- Include penalties for serving malicious JavaScript\n- Mandate source code monitoring and change detection\n\n#### Complete Prevention Strategy\nMost effective controls:\n1. Data layer architecture with API calls to marketing servers\n2. Subresource Integrity implementation\n3. Virtual frame containment deployment\n\n### Implementation Guidelines\n\n1. Implement server-direct data layer architecture for analytics tags\n2. Use Subresource Integrity for all external script requests\n3. Deploy iframe sandboxing for high-risk third-party scripts\n4. Sanitize all dynamic data before including in tag payloads\n5. Maintain updated JavaScript libraries and monitor for vulnerabilities\n6. Establish vendor agreements with security requirements\n7. Regularly audit and monitor third-party script changes"
},
{
"path": "sources/owasp/codeguard-0-threat-modeling.md",
"content": "---\ndescription: Threat Modeling Security\nlanguages:\n- c\n- go\n- java\n- javascript\n- kotlin\n- php\n- python\n- ruby\n- scala\n- swift\n- typescript\nalwaysApply: false\n---\n\n## Threat Modeling Security\n\nStructured process to identify, analyze, and mitigate security threats early in the development lifecycle through systematic security analysis.\n\n### Threat Modeling Process\n\nThe threat modeling process answers four key questions:\n1. What are we working on?\n2. What can go wrong?\n3. What are we going to do about it?\n4. Did we do a good enough job?\n\n### System Modeling (What are we working on?)\n\nCreate visual representations of your system to understand attack surfaces and security boundaries.\n\nData Flow Diagrams (DFDs):\n- Model system interactions with data and external entities\n- Identify trust boundaries, data flows, data stores, and processes\n- Use tools like OWASP Threat Dragon, Microsoft Threat Modeling Tool, or draw.io\n- Create multiple DFDs for complex systems (high-level overview plus detailed sub-systems)\n- Store DFDs in accessible format for updates and reference\n\nKey elements to capture:\n- External entities interacting with the system\n- Data flows between components\n- Data storage locations\n- Process boundaries and trust zones\n- Authentication and authorization points\n\nAlternative approaches:\n- Brainstorming sessions for domain discovery\n- Collaborative definition of key terms and concepts\n- Quick identification of business processes and dependencies\n\n### Threat Identification (What can go wrong?)\n\nUse STRIDE methodology to systematically identify threats within your system context.\n\nSTRIDE Categories:\n\n| Threat Category | Violates | Examples |\n|-----------------|----------|----------|\n| Spoofing | Authenticity | Attacker steals authentication token to impersonate user |\n| Tampering | Integrity | Attacker abuses application to perform unintended database updates |\n| Repudiation | Non-repudiability | Attacker manipulates logs to cover their actions |\n| Information Disclosure | Confidentiality | Attacker extracts data from database containing user account info |\n| Denial of Service | Availability | Attacker locks legitimate user out by failed authentication attempts |\n| Elevation of Privileges | Authorization | Attacker tampers with JWT to change their role |\n\nThreat identification techniques:\n- Systematic review of each STRIDE category for system components\n- Brainstorming sessions with development and security teams\n- Integration with tactical approaches like kill chains or MITRE ATT&CK\n- Use of threat modeling tools for structured analysis\n\nThreat prioritization:\n- Assess likelihood and impact of identified threats\n- Consider cost and effort required for mitigation\n- Focus on threats with highest risk-to-effort ratio\n\n### Response and Mitigations (What are we going to do about it?)\n\nDefine responses for each identified threat using these strategies:\n\nResponse Options:\n- Mitigate: Reduce likelihood that threat will materialize\n- Eliminate: Remove feature or component causing the threat\n- Transfer: Shift responsibility to another entity\n- Accept: Acknowledge risk but take no action due to business constraints\n\nMitigation requirements:\n- Develop actionable mitigation strategies that can be implemented\n- Document mitigations as testable requirements\n- Reference standards like OWASP ASVS and MITRE CWE for guidance\n- Apply mitigations at category or individual threat level\n- Ensure mitigations are built into the system, not theoretical\n\n### Review and Validation (Did we do a good enough job?)\n\nValidate threat model completeness and effectiveness through stakeholder review.\n\nReview criteria:\n- Does the model accurately reflect the actual system?\n- Have all applicable threats been identified?\n- Has a response strategy been defined for each threat?\n- Do mitigation strategies reduce risk to acceptable levels?\n- Is the threat model formally documented and accessible?\n- Can mitigations be tested and measured for effectiveness?\n\nReview participants:\n- Development teams\n- Security teams\n- Architecture teams\n- Product stakeholders\n- Operations teams\n\n### Integration with Development Process\n\nIntegrate threat modeling seamlessly into SDLC:\n- Perform initial threat modeling during design phase\n- Update threat models when system architecture changes\n- Include threat modeling in feature development workflows\n- Treat as standard development step, not optional add-on\n- Maintain and refine models alongside system evolution\n\nDevelopment team considerations:\n- Provide security training for developers\n- Include security experts in threat modeling sessions\n- Use tools that simplify and automate threat identification\n- Promote security culture within development organization\n- Establish cross-team collaboration and communication\n\nTools and techniques:\n- OWASP Threat Dragon for collaborative threat modeling\n- Microsoft Threat Modeling Tool for structured analysis\n- OWASP pytm for threat-modeling-as-code approach\n- draw.io with threat modeling libraries for diagramming\n- STRIDE, PASTA, LINDDUN, OCTAVE, and VAST methodologies\n\n### Implementation Guidelines\n\n1. Start threat modeling early in design phase and integrate into SDLC\n2. Create comprehensive Data Flow Diagrams showing trust boundaries and data flows\n3. Apply STRIDE methodology systematically to identify threats\n4. Prioritize threats based on likelihood, impact, and mitigation cost\n5. Develop actionable, testable mitigation requirements\n6. Involve security experts and cross-functional stakeholders in reviews\n7. Document threat models and store artifacts accessibly\n8. Update threat models when system architecture or features change\n9. Use appropriate tools to support and streamline the process\n10. Foster security awareness and collaboration across development teams"
},
{
"path": "sources/owasp/codeguard-0-transaction-authorization.md",
"content": "---\ndescription: Transaction Authorization Security\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\nalwaysApply: false\n---\n\n## Transaction Authorization Security\n\nSecure implementation of transaction authorization to prevent bypassing of sensitive operations like wire transfers through robust user confirmation and server-side enforcement.\n\n### Transaction Authorization Concept\n\nTransaction authorization requires users to submit a second factor to verify authorization for sensitive operations. This applies beyond financial systems to any operation requiring explicit user consent (account unlocks, privilege changes, data modifications).\n\nAuthorization methods include:\n- Time-based one-time password (OTP) tokens (OATH TOTP)\n- OTP sent by SMS or phone\n- Digital signatures from smart cards or smartphones\n- Challenge-response tokens including unconnected card readers\n- Transaction authorization cards with unique numbers\n\n### Functional Requirements\n\n#### User Identification and Acknowledgment (What You See Is What You Sign)\nTransaction authorization must allow users to identify and acknowledge significant transaction data.\n\nKey principles:\n- User must verify all significant transaction data during authorization process\n- Display critical information: target account, amount, transaction type\n- Balance security requirements with user experience and technical constraints\n- For external devices with limited displays, show minimum significant data (partial account number, amount)\n- Ensure meaningful prompts to prevent social engineering and malware abuse\n\n#### Authorization Token and Method Changes\n- Changes to authorization tokens require authorization using current authorization credentials\n- Changes to authorization methods require authorization using current authorization method\n- Prevent malware from downgrading to least secure authorization method\n- Inform users about potential dangers of different authorization methods\n\n#### Authentication vs Authorization Separation\nDistinguish authentication process from transaction authorization process to prevent credential reuse attacks.\n\nPrevention strategies:\n- Use different methods for authentication and transaction authorization\n- Employ different actions in external security components\n- Present clear messages about what users are signing\n- Prevent malware from using authentication credentials for transaction authorization\n\n#### Unique Authorization per Transaction\nEach transaction requires unique authorization credentials to prevent replay attacks and credential reuse during sessions.\n\n### Non-Functional Requirements\n\n#### Server-Side Enforcement\nAll authorization checks must be performed and enforced server-side.\n\nImplementation requirements:\n- Never allow client-side influence on authorization results\n- Prevent tampering with transaction data parameters\n- Prevent adding/removing parameters that disable authorization checks\n- Apply security programming best practices (default deny, no debug code in production)\n- Encrypt data for confidentiality and integrity, verify server-side\n\n#### Authorization Method Enforcement\nServer-side must enforce chosen authorization method or application policies.\n\nSecurity considerations:\n- Prevent client-side manipulation of authorization method parameters\n- Avoid building new authorization methods on old insecure codebases\n- Ensure attackers cannot downgrade to older, less secure methods\n\n#### Server-Side Transaction Verification\nGenerate and store all significant transaction data server-side.\n\nRequirements:\n- All transaction data must be verified by user and generated server-side\n- Pass data to authorization component without client tampering possibility\n- Prevent malware manipulation of transaction data display\n\n#### Brute-Force Protection\nImplement protections against authorization credential brute-force attacks.\n\nControls:\n- Restart entire transaction authorization process after failed attempts\n- Apply throttling and retry limits\n- Use additional automation prevention techniques\n\n#### Transaction State Control\nEnforce sequential transaction state transitions.\n\nStandard transaction flow:\n1. User enters transaction data\n2. User requests authorization from application\n3. Application initializes authorization mechanism\n4. User verifies/confirms transaction data\n5. User responds with authorization credentials\n6. Application validates authorization and executes transaction\n\nProtection measures:\n- Prevent out-of-order step execution\n- Prevent step skipping\n- Protect against transaction data overwriting before authorization\n- Prevent skipping transaction authorization entirely\n\n#### Transaction Data Protection\nProtect transaction data against modification during authorization process.\n\nImplementation strategies:\n- Invalidate authorization data if transaction data is modified\n- Reset authorization process on transaction data modifications\n- Log, monitor, and investigate modification attempts\n- Prevent Time of Check to Time of Use vulnerabilities\n\n#### Data Confidentiality\nProtect transaction data privacy during all client-server communications throughout the authorization process.\n\n#### Transaction Execution Verification\nImplement final control gate before transaction execution.\n\nVerification requirements:\n- Verify transaction was properly authorized by user\n- Prevent Time of Check to Time of Use attacks\n- Prevent authorization check bypass in transaction entry process\n\n#### Time-Limited Authorization\nLimit authorization credential validity to prevent delayed abuse by malware.\n\nControls:\n- Restrict time window between challenge/OTP generation and authorization completion\n- Balance security with normal user behavior\n- Help prevent resource exhaustion attacks\n\n#### Unique Authorization Credentials\nGenerate unique authorization credentials for every operation to prevent replay attacks.\n\nGeneration methods:\n- Use timestamps in signed transaction data\n- Include sequence numbers in challenges\n- Use random values in authorization components\n\n### Implementation Considerations\n\n#### Risk-Based Authorization\nDetermine which transactions require authorization based on:\n- Risk analysis of specific application\n- Risk exposure assessment\n- Other implemented safeguards\n\n#### Cryptographic Protection\nImplement cryptographic operations to ensure:\n- Transaction integrity\n- Data confidentiality\n- Non-repudiation of transactions\n\n#### Secure Key Management\nProtect device signing keys during device pairing and signing protocol.\n\nSecurity measures:\n- Prevent malware injection/replacement of signing keys\n- Use second factors for key protection (passwords, biometrics)\n- Leverage secure elements (TEE, TPM, smart cards)\n\n#### User Awareness\nTrain users on secure practices:\n- Verify transaction data from trusted sources, not computer screens\n- Understand risks of different authorization mechanisms\n- Recognize social engineering attempts\n\n#### Anti-Malware Integration\nDeploy anti-malware solutions as additional protection layer while recognizing they cannot provide 100% effectiveness.\n\n### Security Controls Summary\n\n1. Implement What You See Is What You Sign principle for transaction data verification\n2. Separate authentication from transaction authorization processes\n3. Use unique, time-limited authorization credentials per transaction\n4. Enforce all authorization logic server-side without client trust\n5. Protect authorization token and method changes through re-authorization\n6. Prevent authorization method downgrade attacks\n7. Implement brute-force protection with transaction resets\n8. Enforce sequential transaction state transitions\n9. Protect transaction data against modification during authorization\n10. Secure all client-server communications with encryption\n11. Verify proper authorization before transaction execution\n12. Use cryptographic signing and secure key storage for integrity\n13. Monitor and log suspicious authorization activities\n14. Provide user education on authorization security practices"
},
{
"path": "sources/owasp/codeguard-0-transport-layer-security.md",
"content": "---\ndescription: Transport Layer Security\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\n- yaml\nalwaysApply: false\n---\n\n## Transport Layer Security\n\nSecure implementation of TLS to protect client-server communications with confidentiality, integrity, and authentication through proper protocol, cipher, and certificate configuration.\n\n\n### TLS Security Benefits\n\nWhen correctly implemented, TLS provides:\n- Confidentiality: Protection against attackers reading traffic contents\n- Integrity: Protection against traffic modification and replay attacks\n- Authentication: Client confirmation of legitimate server connection\n\n### Protocol Security\n\n#### Use Strong TLS Protocols Only\nGeneral purpose web applications should default to TLS 1.3 with TLS 1.2 support if necessary.\n\nProtocol requirements:\n- Enable TLS 1.3 by default\n- Support TLS 1.2 only if legacy client compatibility required\n- Disable TLS 1.0, TLS 1.1, SSL v2, and SSL v3 completely\n- Enable TLS_FALLBACK_SCSV extension to prevent downgrade attacks when fallback necessary\n- Note: PCI DSS forbids legacy protocols such as TLS 1.0\n\n#### Configure Strong Cipher Suites\nUse only strong ciphers that provide adequate security levels.\n\nCipher requirements:\n- Prefer GCM ciphers where possible\n- Always disable null ciphers, anonymous ciphers, and EXPORT ciphers\n- Use Mozilla Foundation secure configuration generator for balanced security and compatibility\n\n#### Set Appropriate Diffie-Hellman Groups\nConfigure secure Diffie-Hellman parameters for key exchange.\n\nTLS 1.3 groups: ffdhe2048, ffdhe3072, ffdhe4096, ffdhe6144, ffdhe8192\n\nConfiguration examples:\n\n```text\n# OpenSSL configuration\nopenssl_conf = openssl_init\n[openssl_init]\nssl_conf = ssl_module\n[ssl_module]\nsystem_default = tls_system_default\n[tls_system_default]\nGroups = x25519:prime256v1:x448:ffdhe2048:ffdhe3072\n```\n\n```text\n# Apache configuration\nSSLOpenSSLConfCmd Groups x25519:secp256r1:ffdhe3072\n```\n\n```text\n# NGINX configuration\nssl_ecdh_curve x25519:secp256r1:ffdhe3072;\n```\n\n#### Disable TLS Compression\nDisable TLS compression to protect against CRIME attacks that could recover sensitive information like session cookies.\n\n#### Keep Cryptographic Libraries Updated\nMaintain current versions of SSL/TLS libraries to protect against vulnerabilities like Heartbleed.\n\n### Certificate Management\n\n#### Use Strong Keys and Protection\nGenerate certificates with minimum 2048-bit key size and protect private keys from unauthorized access using filesystem permissions and access controls.\n\n#### Use Strong Cryptographic Hashing\nCertificates should use SHA-256 for hashing algorithm rather than deprecated MD5 and SHA-1 algorithms.\n\n#### Use Correct Domain Names\nCertificate domain names must match server's FQDN in both commonName (CN) and subjectAlternativeName (SAN) attributes.\n\n#### Consider Wildcard Certificate Risks\nWildcard certificates violate principle of least privilege. Use only when genuine need exists and never for systems at different trust levels.\n\n#### Use Appropriate Certificate Authority\nChoose trusted CAs for Internet-facing applications. Consider LetsEncrypt for free domain validated certificates.\n\n### Application Implementation\n\n#### Use TLS for All Pages\nImplement TLS for entire application with HTTP 301 redirects and HSTS header support.\n\n#### Prevent Mixed Content\nLoad all JavaScript, CSS, and resources over HTTPS to prevent session cookie sniffing and malicious code injection.\n\n#### Use Secure Cookie Flag\nMark all cookies with \"Secure\" attribute to restrict transmission to encrypted HTTPS connections only.\n\n#### Prevent Sensitive Data Caching\nUse cache prevention headers:\n\n```text\nCache-Control: no-cache, no-store, must-revalidate\nPragma: no-cache\nExpires: 0\n```\n\n#### Implement HTTP Strict Transport Security\nHSTS instructs browsers to always request site over HTTPS and prevents bypassing certificate warnings.\n\n#### Consider Client Certificates and Mutual TLS\nmTLS provides mutual authentication but involves significant administrative overhead. Recommended for high-value applications with technically sophisticated users.\n\n#### Avoid Public Key Pinning in Browsers\nHPKP deprecated and no longer supported by modern browsers. Consider pinning only in controlled environments.\n\n### Testing and Validation\n\nTest TLS configuration using tools like SSL Labs Server Test, testssl.sh, SSLyze, and other recommended online and offline testing tools.\n\n### Implementation Guidelines\n\n1. Default to TLS 1.3 with TLS 1.2 fallback only if necessary\n2. Disable all legacy protocols (TLS 1.0/1.1, SSL v2/v3)\n3. Configure strong cipher suites with GCM preference\n4. Set appropriate Diffie-Hellman groups for key exchange\n5. Disable TLS compression to prevent CRIME attacks\n6. Use minimum 2048-bit certificate keys with SHA-256 hashing\n7. Ensure correct domain names in certificate CN and SAN fields\n8. Implement HTTPS for all pages with 301 redirects from HTTP\n9. Prevent mixed content by loading all resources over HTTPS\n10. Set Secure flag on all cookies\n11. Prevent sensitive data caching with appropriate HTTP headers\n12. Implement HSTS for browser enforcement\n13. Consider mTLS for high-value applications\n14. Avoid public key pinning in browsers\n15. Regular testing of TLS configuration with recommended tools"
},
{
"path": "sources/owasp/codeguard-0-unvalidated-redirects-and-forwards.md",
"content": "---\ndescription: Unvalidated Redirects and Forwards Prevention\nlanguages:\n- c\n- java\n- javascript\n- php\n- ruby\n- rust\n- typescript\nalwaysApply: false\n---\n\n## Unvalidated Redirects and Forwards Prevention\n\nPrevent open redirect and forward vulnerabilities by validating all user-controlled redirect destinations to stop phishing attacks and access control bypass.\n\n### Security Risks\n\nUnvalidated redirects and forwards occur when applications accept untrusted input for redirect destinations, enabling:\n- Phishing attacks by redirecting users to malicious sites while maintaining trusted domain appearance\n- Access control bypass by forwarding to privileged functions normally restricted\n- User credential theft through convincing redirect to attacker-controlled sites\n\n### Safe Redirect Examples\n\nSecure redirects use hardcoded URLs that cannot be manipulated by attackers:\n\nJava:\n```java\nresponse.sendRedirect(\"http://www.mysite.com\");\n```\n\nPHP:\n```php\n\n```\n\nASP .NET:\n```csharp\nResponse.Redirect(\"~/folder/Login.aspx\")\n```\n\nRails:\n```ruby\nredirect_to login_path\n```\n\nRust actix web:\n```rust\n Ok(HttpResponse::Found()\n .insert_header((header::LOCATION, \"https://mysite.com/\"))\n .finish())\n```\n\n### Dangerous Redirect Examples\n\nVulnerable code accepts user input directly for redirect destinations:\n\nJava:\n```java\nresponse.sendRedirect(request.getParameter(\"url\"));\n```\n\nPHP:\n```php\n$redirect_url = $_GET['url'];\nheader(\"Location: \" . $redirect_url);\n```\n\nC# .NET:\n```csharp\nstring url = request.QueryString[\"url\"];\nResponse.Redirect(url);\n```\n\nRails:\n```ruby\nredirect_to params[:url]\n```\n\nRust actix web:\n```rust\n Ok(HttpResponse::Found()\n .insert_header((header::LOCATION, query_string.path.as_str()))\n .finish())\n```\n\nASP.NET MVC vulnerable example:\n```csharp\n[HttpPost]\n public ActionResult LogOn(LogOnModel model, string returnUrl)\n {\n if (ModelState.IsValid)\n {\n if (MembershipService.ValidateUser(model.UserName, model.Password))\n {\n FormsService.SignIn(model.UserName, model.RememberMe);\n if (!String.IsNullOrEmpty(returnUrl))\n {\n return Redirect(returnUrl);\n }\n else\n {\n return RedirectToAction(\"Index\", \"Home\");\n }\n }\n else\n {\n ModelState.AddModelError(\"\", \"The user name or password provided is incorrect.\");\n }\n }\n\n // If we got this far, something failed, redisplay form\n return View(model);\n }\n```\n\nAttack example:\n```text\n http://example.com/example.php?url=http://malicious.example.com\n```\n\n### Dangerous Forward Examples\n\nServer-side forwards can bypass access controls when user input determines the forward destination:\n\nJava servlet vulnerable forward:\n```java\npublic class ForwardServlet extends HttpServlet\n{\n protected void doGet(HttpServletRequest request, HttpServletResponse response)\n throws ServletException, IOException {\n String query = request.getQueryString();\n if (query.contains(\"fwd\"))\n {\n String fwd = request.getParameter(\"fwd\");\n try\n {\n request.getRequestDispatcher(fwd).forward(request, response);\n }\n catch (ServletException e)\n {\n e.printStackTrace();\n }\n }\n }\n}\n```\n\nAttack example:\n```text\nhttp://www.example.com/function.jsp?fwd=admin.jsp\n```\n\n### Prevention Strategies\n\n#### Avoid User Input for Destinations\nSimply avoid using redirects and forwards, or do not allow URLs as user input for destinations.\n\n#### Use Server-Side Mapping\nHave users provide short name, ID, or token mapped server-side to full target URL.\n\nBenefits:\n- Highest degree of protection against URL tampering\n- Prevents direct URL manipulation\n\nConsiderations:\n- Prevent enumeration vulnerabilities where users cycle through IDs\n- Use sufficiently large or complex token spaces\n\n#### Input Validation and Authorization\nIf user input cannot be avoided:\n- Ensure supplied value is valid and appropriate for the application\n- Verify user is authorized for the redirect/forward target\n- Validate before performing redirect or forward\n\n#### Allow-List Approach\nCreate and enforce list of trusted URLs or hosts:\n- Use allow-list approach rather than deny-list\n- Sanitize input against trusted URL list\n- Consider regex patterns for flexible matching\n\n#### External Redirect Warning\nForce external redirects through interstitial warning page:\n- Clearly display destination to users\n- Require user confirmation before proceeding\n- Helps users identify potential phishing attempts\n\n#### Framework-Specific Considerations\n\nPHP:\n- Always follow header(\"Location: ...\") with exit; to stop execution\n- Prevents continued code execution after redirect\n\nASP.NET MVC:\n- MVC 1 & 2 particularly vulnerable to open redirection attacks\n- Use MVC 3 or later to avoid vulnerabilities\n\n### Implementation Guidelines\n\n1. Use hardcoded URLs for redirects whenever possible\n2. Implement server-side mapping for user-controlled redirects\n3. Validate all user input against allow-list of permitted destinations\n4. Verify user authorization before performing redirects or forwards\n5. Use interstitial warnings for external redirects\n6. Follow framework-specific security practices\n7. Prevent enumeration through complex token spaces\n8. Keep frameworks updated with security patches\n9. Never trust user input for determining redirect destinations\n10. Test redirect functionality for bypass attempts"
},
{
"path": "sources/owasp/codeguard-0-user-privacy-protection.md",
"content": "---\ndescription: User Privacy Protection Rule\nlanguages:\n- c\n- go\n- java\n- javascript\n- kotlin\n- python\n- ruby\n- swift\n- typescript\nalwaysApply: false\n---\n\n- Implement strong cryptography, enforce HTTPS with HSTS, enable certificate pinning,\nand provide user privacy features to protect data and anonymity.\n- Use strong, up-to-date cryptographic algorithms for data in transit and at rest; securely hash passwords with established libraries.\n- Enforce HTTPS exclusively and implement HTTP Strict Transport Security (HSTS).\n- Implement certificate pinning to prevent man-in-the-middle attacks even if CAs are compromised.\n- Minimize IP address leakage by blocking third-party external content loading where feasible.\n- Maintain transparency by informing users about privacy limitations and data handling policies.\n- Implement privacy-focused audit trails and access logging.\n- Return \"Invalid username or password\" to prevent account enumeration\n- Use Argon2 or bcrypt with unique salts per user\n- Store sessions server-side with cryptographically random IDs"
},
{
"path": "sources/owasp/codeguard-0-virtual-patching.md",
"content": "---\ndescription: Virtual Patching Security\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\n- xml\nalwaysApply: false\n---\n\n## Virtual Patching Security\n\nImplement temporary security controls to protect against known vulnerabilities while developing permanent code fixes through security policy enforcement layers.\n\n### Virtual Patching Definition\n\nA security policy enforcement layer which prevents and reports exploitation attempts of known vulnerabilities. Virtual patches analyze transactions and intercept attacks in transit so malicious traffic never reaches the web application, providing protection while actual source code remains unmodified.\n\n### When Virtual Patching is Needed\n\nVirtual patching addresses real-world scenarios where immediate code fixes are not feasible:\n\n- Lack of resources: Developers allocated to other projects\n- Third-party software: Code cannot be modified by users\n- Outsourced development: Changes require new project authorization\n\nImportant: Code level fixes and virtual patching are NOT mutually exclusive. They are executed by different teams (developers vs. security operations) and can run in tandem.\n\n### Virtual Patching Goals\n\n- Minimize Time-to-Fix: Implement mitigation as soon as possible while code fixes are developed\n- Attack Surface Reduction: Focus on minimizing attack vectors, even partial reduction (50% in 10 minutes vs 100% in 48 hours)\n\n### Virtual Patching Tools\n\nAvailable tools for implementing virtual patches:\n- Intermediary devices such as WAF or IPS appliances\n- Web server plugins such as ModSecurity\n- Application layer filters such as ESAPI WAF\n\n### Virtual Patching Methodology\n\nFollow structured workflow for consistent, repeatable virtual patching:\n\n1. Preparation\n2. Identification \n3. Analysis\n4. Virtual Patch Creation\n5. Implementation/Testing\n6. Recovery/Follow-Up\n\n### Preparation Phase\n\nCritical preparation items before incidents occur:\n\n- Public/Vendor Vulnerability Monitoring: Subscribe to vendor alert mailing lists for commercial software\n- Virtual Patching Pre-Authorization: Expedite governance processes since virtual patches don't modify source code\n- Deploy Virtual Patching Tools in Advance: Install ModSecurity WAF or similar tools ready for activation\n- Increase HTTP Audit Logging: Capture request URI, full headers, request/response bodies for incident analysis\n\n### Analysis Phase\n\nRecommended analysis steps:\n\n1. Determine virtual patching applicability for vulnerability type\n2. Utilize bug tracking system for vulnerability information management\n3. Verify vulnerability identifier (CVE name/number)\n4. Designate impact level for proper prioritization\n5. Specify affected software versions\n6. List configuration requirements to trigger vulnerability\n7. Collect Proof of Concept (PoC) exploit code for analysis and testing\n\n### Virtual Patch Creation Principles\n\nTwo main requirements for accurate virtual patches:\n- No false positives: Never block legitimate traffic\n- No false negatives: Never miss attacks, even with evasion attempts\n\n### Positive Security (Allow List) Virtual Patches (Recommended)\n\nPositive security model provides comprehensive input validation by specifying valid input characteristics and denying anything non-conformant.\n\nExample ModSecurity virtual patch for SQL injection protection:\n\n```text\n##\n## Verify we only receive 1 parameter called \"reqID\"\n##\nSecRule REQUEST_URI \"@contains /wp-content/plugins/levelfourstorefront/scripts/administration/exportsubscribers.php\" \"chain,id:1,phase:2,t:none,t:Utf8toUnicode,t:urlDecodeUni,t:normalizePathWin,t:lowercase,block,msg:'Input Validation Error for \\'reqID\\' parameter - Duplicate Parameters Names Seen.',logdata:'%{matched_var}'\"\n SecRule &ARGS:/reqID/ \"!@eq 1\"\n\n##\n## Verify reqID's payload only contains integers\n##\nSecRule REQUEST_URI \"@contains /wp-content/plugins/levelfourstorefront/scripts/administration/exportsubscribers.php\" \"chain,id:2,phase:2,t:none,t:Utf8toUnicode,t:urlDecodeUni,t:normalizePathWin,t:lowercase,block,msg:'Input Validation Error for \\'reqID\\' parameter.',logdata:'%{args.reqid}'\"\n SecRule ARGS:/reqID/ \"!@rx ^[0-9]+$\"\n```\n\n### Negative Security (Block List) Virtual Patches\n\nNegative security model detects specific known attacks rather than allowing only valid traffic.\n\nExample PoC attack payload:\n```text\nhttp://localhost/wordpress/wp-content/plugins/levelfourstorefront/scripts/administration/exportsubscribers.php?reqID=1' or 1='1\n```\n\nExample ModSecurity block list virtual patch:\n```text\nSecRule REQUEST_URI \"@contains /wp-content/plugins/levelfourstorefront/scripts/administration/exportsubscribers.php\" \"chain,id:1,phase:2,t:none,t:Utf8toUnicode,t:urlDecodeUni,t:normalizePathWin,t:lowercase,block,msg:'Input Validation Error for \\'reqID\\' parameter.',logdata:'%{args.reqid}'\"\n SecRule ARGS:/reqID/ \"@pm '\"\n```\n\n### Security Model Comparison\n\nPositive vs Negative Security considerations:\n- Negative security: Faster implementation but more evasion possibilities\n- Positive security: Better protection but manual process, less scalable for large/dynamic sites\n- Positive security recommended for specific vulnerability locations identified by alerts\n\n### Avoid Exploit-Specific Patches\n\nResist creating patches that only block exact exploit payloads. Example poor approach for XSS:\n\n```html\n\n```\n\nBlocking only this exact payload provides minimal long-term protection value.\n\n### Automated Virtual Patch Creation\n\nTools for automated patch creation from vulnerability reports:\n- OWASP ModSecurity Core Rule Set (CRS) Scripts: Auto-convert XML output from tools like ZAP\n- ThreadFix Virtual Patching: Convert vulnerability XML data into ModSecurity patches\n- Direct WAF Importing: Commercial WAF products import DAST tool XML reports\n\n### Implementation and Testing\n\nTesting tools for virtual patch validation:\n- Web browsers\n- Command-line clients (Curl, Wget)\n- Local proxy servers (ZAP)\n- ModSecurity AuditViewer for log manipulation and re-injection\n\nTesting steps:\n- Implement patches initially in \"Log Only\" mode to prevent false positives\n- Request retest from vulnerability identification team\n- Return to analysis phase if evasions occur during retesting\n\n### Recovery and Follow-Up\n\nPost-implementation activities:\n- Update ticket system with virtual patch details and rule IDs\n- Conduct periodic re-assessments to determine when virtual patches can be removed\n- Run virtual patch alert reports to demonstrate protection value\n- Track time-to-fix metrics for different vulnerability types\n\n### Developer Integration Guidelines\n\n1. Prioritize permanent code fixes over virtual patches\n2. Collaborate with security teams on virtual patch requirements and testing\n3. Understand virtual patch limitations and temporary nature\n4. Provide input on normal application behavior for positive security rules\n5. Review virtual patch logs for attack patterns that inform secure coding practices\n6. Plan code fixes to address root causes protected by virtual patches\n7. Participate in virtual patch removal process once code fixes are deployed\n8. Document application-specific requirements for virtual patch creation"
},
{
"path": "sources/owasp/codeguard-0-vulnerable-dependency-management.md",
"content": "---\ndescription: Vulnerable Dependency Management\nlanguages:\n- c\n- go\n- javascript\n- r\n- xml\nalwaysApply: false\n---\n\n## Vulnerable Dependency Management\n\nDetect and mitigate security vulnerabilities in third-party dependencies through automated scanning, proper testing, and systematic remediation approaches.\n\n### Automated Detection\n\nIntegrate vulnerability scanning from project inception using tools that cover multiple vulnerability sources:\n- CVE databases (NIST National Vulnerability Database)\n- Full disclosure sources (mailing lists, Exploit-DB)\n- Provider-specific vulnerability feeds\n\nRecommended tools:\n- OWASP Dependency Check (Java, .NET, experimental support for Python, Ruby, PHP, Node.js, C/C++)\n- NPM Audit (Node.js, JavaScript)\n- OWASP Dependency Track (organization-wide management)\n\n### Remediation Cases\n\nCase 1 - Patched version available:\n1. Update dependency version in testing environment\n2. Run automated tests to verify functionality\n3. If tests pass: deploy to production\n4. If tests fail: update application code for API changes or report incompatibility to provider\n\nCase 2 - Patch delayed, provider provides workaround:\n1. Apply provider workaround if available\n2. If provider lists impacted functions, add protective wrappers\n3. Validate workaround in testing environment\n\nExample protective wrapper for RCE vulnerability:\n```java\npublic void callFunctionWithRCEIssue(String externalInput){\n //Apply input validation on the external input using regex\n if(Pattern.matches(\"[a-zA-Z0-9]{1,50}\", externalInput)){\n //Call the flawed function using safe input\n functionWithRCEIssue(externalInput);\n }else{\n //Log the detection of exploitation\n SecurityLogger.warn(\"Exploitation of the RCE issue XXXXX detected !\");\n //Raise an exception leading to a generic error send to the client...\n }\n}\n```\n\nCase 3 - No patch available:\n1. Analyze CVE description to understand vulnerability type (SQL injection, XSS, XXE, etc.)\n2. Identify all application code calling the vulnerable dependency\n3. Implement compensating controls based on vulnerability type\n4. Create unit tests to verify protection effectiveness\n5. For open source dependencies: consider creating and contributing patches\n\nCase 4 - Previously unknown vulnerability discovered:\n1. Notify provider with vulnerability details\n2. If provider cooperates: follow Case 2 approach\n3. If provider unresponsive: follow Case 3 approach\n\n### Dependencies Analysis\n\nTransitive dependencies: Act on direct dependencies when possible, as modifying transitive dependencies requires understanding complex dependency chains and can impact application stability.\n\nUse dependency management tools to identify:\n- Direct vs transitive dependency relationships\n- All code paths using vulnerable components\n- Impact scope of potential vulnerabilities\n\n### Testing and Validation\n\nMaintain comprehensive automated tests covering:\n- Features using impacted dependencies\n- Security controls added as mitigations\n- Regression detection during updates\n\nRun tests before and after dependency updates to ensure:\n- Application functionality remains intact\n- Security mitigations are effective\n- No new vulnerabilities are introduced\n\n### Risk Management\n\nDocument all vulnerability decisions including:\n- Technical analysis and CVSS scoring\n- Chosen mitigation approach and rationale\n- Testing results and validation steps\n- Risk acceptance decisions with business justification\n\nEscalate risk acceptance decisions to Chief Risk Officer after thorough technical analysis.\n\n### Continuous Monitoring\n\nImplement continuous dependency scanning in CI/CD pipelines:\n- Scan on every build\n- Fail builds for high-severity vulnerabilities\n- Generate reports for security team review\n- Track remediation progress and compliance\n\nChoose tools supporting false-positive flagging and multiple reliable input sources to handle different vulnerability disclosure methods.\n\n### Prevention Guidelines\n\n- Start dependency scanning from project inception\n- Prefer fixing vulnerabilities at source (application or dependency) over external controls\n- Keep dependencies updated regularly\n- Monitor dependencies for maintenance status and community activity\n- Consider dependency complexity and transitive dependency count when selecting libraries"
},
{
"path": "sources/owasp/codeguard-0-web-service-security.md",
"content": "---\ndescription: Web Service Security\nlanguages:\n- c\n- go\n- java\n- javascript\n- php\n- python\n- ruby\n- typescript\n- xml\nalwaysApply: false\n---\n\n## Web Service Security\n\nSecure web services through transport protection, authentication, input validation, and XML attack prevention.\n\n### Transport Security\n\nAll web service communications with sensitive features or data must use well-configured TLS. TLS provides confidentiality, integrity protection, replay defenses, and server authentication.\n\nServer certificate validation requirements:\n- Issued by trusted provider\n- Not expired or revoked\n- Matches service domain name\n- Proven private key ownership\n\n### Authentication\n\n- Avoid Basic Authentication; use Client Certificate Authentication with Mutual-TLS when appropriate\n- Enforce consistent encoding styles between client and server\n\n### Message Protection\n\nFor XML data requiring integrity beyond TLS:\n- Use XML digital signatures with sender's private key\n- Encrypt sensitive data with strong ciphers for both transport and at-rest protection when required\n\n### Authorization\n\n- Authorize clients for every web service method and request\n- Check privileges for requested resources on every request\n- Separate administrative functions from regular service endpoints\n- Add challenge-response mechanisms for sensitive operations (password changes, contact details, payment instructions)\n\n### Input Validation\n\nSchema validation:\n- Validate SOAP payloads against XML schema definition (XSD)\n- Define maximum length and character sets for all parameters\n- Use strong allow-list patterns for fixed format parameters (zip codes, phone numbers)\n\nContent validation for XML input:\n- Validate against malformed XML entities\n- Validate against XML Bomb attacks\n- Use strong allowlists for input validation\n- Validate against external entity attacks\n\n### XML Attack Protection\n\nConfigure XML parsers to protect against:\n- Recursive payloads\n- Oversized payloads\n- XML entity expansion\n- Overlong element names (SOAP Actions)\n\nBuild test cases to verify parser resistance to these attacks.\n\n### Output Protection\n\nApply proper output encoding to prevent XSS when web service data is consumed by web clients.\n\n### Resource Protection\n\n- Limit SOAP message sizes to prevent DoS attacks\n- Limit CPU cycles, memory usage, and simultaneous connections\n- Optimize configuration for maximum message throughput\n- Implement virus scanning for SOAP attachments before storage\n\n### Compliance\n\nEnsure compliance with Web Services-Interoperability (WS-I) Basic Profile for security baseline."
},
{
"path": "sources/owasp/codeguard-0-xml-external-entity-prevention.md",
"content": "---\ndescription: XML External Entity Prevention\nlanguages:\n- c\n- java\n- matlab\n- php\n- python\n- swift\n- xml\nalwaysApply: false\n---\n\n## XML External Entity Prevention\n\nPrevent XXE attacks by disabling DTDs and external entities in XML parsers. Safest approach: disable DTDs completely.\n\n### General Principle\n\n```java\nfactory.setFeature(\"http://apache.org/xml/features/disallow-doctype-decl\", true);\n```\n\nDisabling DTDs protects against XXE and Billion Laughs attacks. If DTDs cannot be disabled, disable external entities using parser-specific methods.\n\n### Java\n\nJava parsers have XXE enabled by default.\n\nDocumentBuilderFactory/SAXParserFactory/DOM4J:\n\n```java\nDocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();\nString FEATURE = null;\ntry {\n // PRIMARY defense - disallow DTDs completely\n FEATURE = \"http://apache.org/xml/features/disallow-doctype-decl\";\n dbf.setFeature(FEATURE, true);\n dbf.setXIncludeAware(false);\n} catch (ParserConfigurationException e) {\n logger.info(\"ParserConfigurationException was thrown. The feature '\" + FEATURE\n + \"' is not supported by your XML processor.\");\n}\n```\n\nIf DTDs cannot be completely disabled:\n\n```java\nDocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();\nString[] featuresToDisable = {\n \"http://xml.org/sax/features/external-general-entities\",\n \"http://xml.org/sax/features/external-parameter-entities\",\n \"http://apache.org/xml/features/nonvalidating/load-external-dtd\"\n};\n\nfor (String feature : featuresToDisable) {\n try { \n dbf.setFeature(feature, false); \n } catch (ParserConfigurationException e) {\n logger.info(\"ParserConfigurationException was thrown. The feature '\" + feature\n + \"' is probably not supported by your XML processor.\");\n }\n}\ndbf.setXIncludeAware(false);\ndbf.setExpandEntityReferences(false);\ndbf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);\n```\n\nXMLInputFactory (StAX):\n```java\nxmlInputFactory.setProperty(XMLInputFactory.SUPPORT_DTD, false);\n// Or if DTDs needed:\nxmlInputFactory.setProperty(XMLConstants.ACCESS_EXTERNAL_DTD, \"\");\nxmlInputFactory.setProperty(\"javax.xml.stream.isSupportingExternalEntities\", false);\n```\n\nTransformerFactory:\n```java\nTransformerFactory tf = TransformerFactory.newInstance();\ntf.setAttribute(XMLConstants.ACCESS_EXTERNAL_DTD, \"\");\ntf.setAttribute(XMLConstants.ACCESS_EXTERNAL_STYLESHEET, \"\");\n```\n\nXMLReader:\n```java\nXMLReader reader = XMLReaderFactory.createXMLReader();\nreader.setFeature(\"http://apache.org/xml/features/disallow-doctype-decl\", true);\nreader.setFeature(\"http://apache.org/xml/features/nonvalidating/load-external-dtd\", false);\nreader.setFeature(\"http://xml.org/sax/features/external-general-entities\", false);\nreader.setFeature(\"http://xml.org/sax/features/external-parameter-entities\", false);\n```\n\nSAXBuilder:\n```java\nSAXBuilder builder = new SAXBuilder();\nbuilder.setFeature(\"http://apache.org/xml/features/disallow-doctype-decl\",true);\nDocument doc = builder.build(new File(fileName));\n```\n\nNo-op EntityResolver:\n```java\npublic final class NoOpEntityResolver implements EntityResolver {\n public InputSource resolveEntity(String publicId, String systemId) {\n return new InputSource(new StringReader(\"\"));\n }\n}\nxmlReader.setEntityResolver(new NoOpEntityResolver());\ndocumentBuilder.setEntityResolver(new NoOpEntityResolver());\n```\n\nNever use java.beans.XMLDecoder on untrusted content - it can execute arbitrary code.\n\n### .NET\n\nXmlReader (.NET 4.5.2+ safe by default):\n```csharp\nXmlReaderSettings settings = new XmlReaderSettings();\nsettings.DtdProcessing = DtdProcessing.Prohibit;\nsettings.XmlResolver = null;\nXmlReader reader = XmlReader.Create(stream, settings);\n```\n\nXmlTextReader (prior to .NET 4.0):\n```csharp\nXmlTextReader reader = new XmlTextReader(stream);\nreader.ProhibitDtd = true; \n```\n\nXmlTextReader (.NET 4.0 - 4.5.2):\n```csharp\nXmlTextReader reader = new XmlTextReader(stream);\nreader.DtdProcessing = DtdProcessing.Prohibit; \n```\n\nXmlDocument (prior to 4.5.2):\n```csharp\nXmlDocument xmlDoc = new XmlDocument();\nxmlDoc.XmlResolver = null;\nxmlDoc.LoadXml(xml);\n```\n\nXPathNavigator (prior to 4.5.2):\n```csharp\nXmlReader reader = XmlReader.Create(\"example.xml\");\nXPathDocument doc = new XPathDocument(reader);\nXPathNavigator nav = doc.CreateNavigator();\nstring xml = nav.InnerXml.ToString();\n```\n\n### C/C++\n\nlibxml2: Avoid XML_PARSE_NOENT and XML_PARSE_DTDLOAD options.\n\nlibxerces-c:\n```cpp\nXercesDOMParser *parser = new XercesDOMParser;\nparser->setCreateEntityReferenceNodes(true);\nparser->setDisableDefaultEntityResolution(true);\n\nSAXParser* parser = new SAXParser;\nparser->setDisableDefaultEntityResolution(true);\n\nSAX2XMLReader* reader = XMLReaderFactory::createXMLReader();\nparser->setFeature(XMLUni::fgXercesDisableDefaultEntityResolution, true);\n```\n\n### PHP\n\nPHP 8.0+ prevents XXE by default. Earlier versions:\n```php\nlibxml_set_external_entity_loader(null);\n```\n\n### Python\n\n```python\nfrom defusedxml import ElementTree as ET\ntree = ET.parse('filename.xml')\n\n# Or with lxml:\nfrom lxml import etree\nparser = etree.XMLParser(resolve_entities=False, no_network=True)\ntree = etree.parse('filename.xml', parser)\n```\n\n### iOS/macOS\n\n```swift\nlet options: NSXMLNodeOptions = .documentTidyXML\nlet xmlDoc = try NSXMLDocument(data: data, options: options.union(.nodeLoadExternalEntitiesNever))\n```\n\n### ColdFusion\n\nAdobe ColdFusion:\n```\n\n\n\na = XmlParse(\"xml.xml\", false, parseroptions);\n\n```\n\nLucee (Application.cfc):\n```\nthis.xmlFeatures = {\n externalGeneralEntities: false,\n secure: true,\n disallowDoctypeDecl: true\n};\n```\n\n### Additional Measures\n\n- Update XML libraries regularly\n- Validate XML input before parsing\n- Use static analysis tools for XXE detection\n- Test with XXE payloads in safe environments\n\n### When DTDs Required\n\nIf DTDs absolutely necessary:\n- Use custom EntityResolver with restricted entities\n- Implement strict entity allowlisting\n- Preprocess XML to remove dangerous DOCTYPE declarations"
},
{
"path": "sources/owasp/codeguard-0-xml-security.md",
"content": "---\ndescription: XML Security Rule\nlanguages:\n- xml\nalwaysApply: false\n---\n\nEnforce robust XML security practices to prevent XXE, SSRF, DoS, schema poisoning, and data integrity issues in XML parsing and validation.\n\n- Always reject unexpected elements, attributes, or data outside the schema definitions.\n- Perform business logic validation on XML data after schema validation (e.g., numeric ranges on payment amounts).\n- Keep XML processing libraries up to date and use secure configurations by default.\n\nUse a standards-compliant XML parser configured to disable DTD processing and external entity resolution to prevent XXE and entity expansion attacks.\n- Ensure your XML parser rejects malformed XML documents and halts processing on fatal errors.\n- Configure parser features such as `disallow-doctype-decl`, `external-general-entities`, and `external-parameter-entities` set to false or disabled.\n\nValidate all XML documents strictly against local, trusted XML Schemas (XSDs) with narrow data type restrictions and clearly defined element occurrence limits.\n- Avoid or limit the use of DTDs; prefer comprehensive XSD validation.\n- Use schemas with explicit types, length limits, regex patterns, enumerations, and xs:assertion where appropriate.\n- Set maxOccurs explicitly to control element multiplicity.\n- Store schemas locally with strict filesystem permissions and never load schemas over unencrypted HTTP.\n\nPrevent resource exhaustion by rejecting XML documents with excessive depth, nested unclosed tags, or large size to avoid DoS.\n- Enforce limits on XML element nesting depth and document size.\n- Test parser CPU usage differences between valid and malformed XML inputs.\n- Reject or timeout processing on unexpectedly complex documents.\n\nBlock or sandbox XML processing from making remote network calls to mitigate SSRF and information disclosure risks.\n- Disable external entity resolution or restrict it to local, whitelisted resources only.\n - Validate and sanitize all external URI references in XML entities.\n- Monitor for unexpected DNS lookups or network activity during XML parsing.\n\nLog and monitor XML parsing errors and rejections to detect injection attempts, malformed XML attacks, or schema poisoning.\n- Capture detailed error information without exposing sensitive data.\n - Alert on repeated or suspicious XML parse failures.\n- Audit local schema files regularly for unauthorized changes."
},
{
"path": "sources/owasp/codeguard-0-xs-leaks.md",
"content": "---\ndescription: Preventing Cross-Site Leaks (XS-Leaks)\nlanguages:\n- c\n- javascript\n- typescript\nalwaysApply: false\n---\n\nProtecting your applications from Cross-Site Leaks is crucial for safeguarding user privacy. XS-Leaks are a class of vulnerabilities that exploit subtle browser behaviors to extract sensitive user information across origins. \n\nXS-Leaks occur when an attacker's website can infer information about a user's state on another website through side-channels like:\n\n- Error messages\n- Frame counting\n- Resource timing\n- Cache probing\n- Response size detection\n\nThese attacks can reveal sensitive information such as whether a user is logged in, specific account details, or even extract data from cross-origin resources.\n\nProperly configured cookies are your first line of defense against XS-Leaks. For example:\n\n```javascript\n// Setting cookies in JavaScript with secure attributes\ndocument.cookie = \"sessionId=abc123; SameSite=Strict; Secure; HttpOnly; Path=/\";\n```\n\nFor server-side cookie setting (example in Express.js):\n\n```javascript\napp.use(session({\n secret: 'your-secret-key',\n cookie: {\n sameSite: 'strict', // Options: strict, lax, none\n secure: true, // Requires HTTPS\n httpOnly: true // Prevents JavaScript access\n }\n}));\n```\n\nIn your HTTP response headers:\n\n```http\nSet-Cookie: sessionId=abc123; SameSite=Strict; Secure; HttpOnly; Path=/\n```\n\n\n\n* Always specify a `SameSite` attribute:\n * Use `SameSite=Strict` for cookies related to sensitive actions\n * Use `SameSite=Lax` for cookies needed on normal navigation to your site\n * Use `SameSite=None; Secure` only when third-party usage is absolutely required\n\n* Never rely on browser defaults as they may vary across browsers and versions\n\n### Framing Protection\n\nPrevent your site from being framed by potentially malicious sites:\n\n```javascript\n// In your Express.js application\napp.use((req, res, next) => {\n // CSP frame-ancestors directive (modern approach)\n res.setHeader(\n 'Content-Security-Policy',\n \"frame-ancestors 'self' https://trusted-parent.com\"\n );\n \n // X-Frame-Options (legacy fallback)\n res.setHeader('X-Frame-Options', 'SAMEORIGIN');\n \n next();\n});\n```\n\nUse Fetch Metadata headers to detect and block suspicious cross-origin requests:\n\n```javascript\n// Express.js middleware for protecting sensitive endpoints\nfunction secureEndpoint(req, res, next) {\n // Get Fetch Metadata headers\n const fetchSite = req.get('Sec-Fetch-Site') || 'unknown';\n const fetchMode = req.get('Sec-Fetch-Mode') || 'unknown';\n const fetchDest = req.get('Sec-Fetch-Dest') || 'unknown';\n \n // Block cross-site requests to sensitive endpoints\n if (fetchSite === 'cross-site' && req.path.startsWith('/api/sensitive')) {\n return res.status(403).send('Cross-site requests not allowed');\n }\n \n // Block embedding in iframes from untrusted sites\n if (fetchDest === 'iframe' && fetchSite === 'cross-site') {\n return res.status(403).send('Embedding not allowed');\n }\n \n next();\n}\n\napp.use(secureEndpoint);\n```\n\n### Secure Cross-Origin Communication\n\nWhen using `postMessage` for cross-origin communication:\n\n```javascript\n// UNSAFE - Never do this\nwindow.postMessage(sensitiveData, '*');\n\n// SAFE - Always specify the exact target origin\nwindow.postMessage(sensitiveData, 'https://trusted-receiver.com');\n\n// When receiving messages, always verify the origin\nwindow.addEventListener('message', (event) => {\n // Always verify message origin\n if (event.origin !== 'https://trusted-sender.com') {\n console.error('Received message from untrusted origin:', event.origin);\n return;\n }\n \n // Process the message\n processMessage(event.data);\n});\n```\n\n### Isolating Browsing Contexts\n\nUse Cross-Origin-Opener-Policy (COOP) to isolate your site from potential attackers:\n\n```http\nCross-Origin-Opener-Policy: same-origin\n```\n\nIn Express.js:\n\n```javascript\napp.use((req, res, next) => {\n res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');\n next();\n});\n```\n\nFor maximum isolation, combine with Cross-Origin-Embedder-Policy (COEP):\n\n```javascript\napp.use((req, res, next) => {\n res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');\n res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');\n next();\n});\n```\n\n### Preventing Cache-Based Leaks\n\nProtect sensitive resources from cache probing attacks:\n\n```javascript\n// Express.js middleware for sensitive endpoints\napp.get('/api/sensitive-data', (req, res) => {\n // Add user-specific token to prevent cache probing\n const userToken = req.user.securityToken;\n \n // Disable caching for sensitive resources\n res.setHeader('Cache-Control', 'no-store');\n res.setHeader('Pragma', 'no-cache');\n \n // Add user token to response to ensure uniqueness\n const data = { userToken, sensitiveData: 'secret information' };\n res.json(data);\n});\n```\n\nFor static resources that might reveal user state:\n\n```javascript\n// Add user-specific tokens to URLs of sensitive resources\nfunction getUserSpecificUrl(baseUrl) {\n const userToken = generateUserToken();\n return `${baseUrl}?token=${userToken}`;\n}\n\nconst profileImageUrl = getUserSpecificUrl('/images/profile.jpg');\n```\n\n### Comprehensive Defense Strategy\n\nImplement these headers for a robust defense against XS-Leaks:\n\n```javascript\napp.use((req, res, next) => {\n // Framing protection\n res.setHeader('Content-Security-Policy', \"frame-ancestors 'self'\");\n res.setHeader('X-Frame-Options', 'SAMEORIGIN');\n \n // Resource isolation\n res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');\n res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');\n \n // Cache control for dynamic content\n if (req.path.startsWith('/api/')) {\n res.setHeader('Cache-Control', 'no-store');\n }\n \n next();\n});\n```"
},
{
"path": "sources/owasp/codeguard-0-xss-filter-evasion.md",
"content": "---\ndescription: XSS Filter Evasion Prevention - Advanced techniques attackers use to\n bypass input filtering and blacklists\nlanguages:\n- c\n- javascript\n- typescript\nalwaysApply: false\n---\n\nRelying solely on input filtering or blacklists is insufficient because attackers use numerous techniques to bypass these defenses:\n\n- Mixed encoding schemes: Combining HTML, URL, and Unicode encodings\n- Whitespace manipulation: Using tabs, newlines, and other whitespace characters to confuse parsers\n- Malformed tags: Creating deliberately broken HTML that browsers will \"fix\" during rendering\n- Obfuscation: Using JavaScript encoding functions like `String.fromCharCode()` to hide malicious code\n\n### Context-Aware Output Encoding\n\nThe most effective defense is to apply the appropriate encoding based on where the data will be used:\n\n#### HTML Context (Content between tags)\n\n```javascript\n// VULNERABLE\nconst userName = request.getParameter(\"user\");\ndocument.getElementById(\"welcome\").innerHTML = \"Hello, \" + userName;\n\n// SECURE\nimport { encodeForHTML } from 'your-encoding-library';\nconst userName = request.getParameter(\"user\");\ndocument.getElementById(\"welcome\").innerHTML = \"Hello, \" + encodeForHTML(userName);\n```\n\n#### HTML Attribute Context\n\n```javascript\n// VULNERABLE\nconst userColor = request.getParameter(\"color\");\ndocument.getElementById(\"profile\").innerHTML = \n `Profile
`;\n\n// SECURE\nimport { encodeForHTMLAttribute } from 'your-encoding-library';\nconst userColor = request.getParameter(\"color\");\ndocument.getElementById(\"profile\").innerHTML = \n `Profile
`;\n```\n\n#### JavaScript Context\n\n```javascript\n// VULNERABLE\nconst userInput = request.getParameter(\"input\");\nconst script = document.createElement(\"script\");\nscript.textContent = `const userValue = \"${userInput}\";`;\n\n// SECURE\nimport { encodeForJavaScript } from 'your-encoding-library';\nconst userInput = request.getParameter(\"input\");\nconst script = document.createElement(\"script\");\nscript.textContent = `const userValue = \"${encodeForJavaScript(userInput)}\";`;\n```\n\n#### URL Context\n\n```javascript\n// VULNERABLE\nconst redirectUrl = request.getParameter(\"url\");\nlocation.href = redirectUrl;\n\n// SECURE\nimport { encodeForURL } from 'your-encoding-library';\nconst redirectUrl = request.getParameter(\"url\");\n// Validate URL pattern first\nif (isValidRedirectURL(redirectUrl)) {\n location.href = encodeForURL(redirectUrl);\n}\n```\n\n#### CSS Context\n\n```javascript\n// VULNERABLE\nconst userTheme = request.getParameter(\"theme\");\ndocument.getElementById(\"custom\").style = userTheme;\n\n// SECURE\nimport { encodeForCSS } from 'your-encoding-library';\nconst userTheme = request.getParameter(\"theme\");\ndocument.getElementById(\"custom\").style = encodeForCSS(userTheme);\n```\n\n### Using Established Sanitization Libraries\n\nAvoid creating your own sanitization logic. Use well-maintained libraries instead:\n\n#### JavaScript/DOM\n\n```javascript\n// Using DOMPurify\nimport DOMPurify from 'dompurify';\n\nfunction displayUserContent(content) {\n // Configure DOMPurify to only allow specific tags and attributes\n const config = {\n ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a', 'p', 'ul', 'ol', 'li'],\n ALLOWED_ATTR: ['href', 'target']\n };\n \n const sanitized = DOMPurify.sanitize(content, config);\n document.getElementById('user-content').innerHTML = sanitized;\n}\n```\n\n#### Java\n\n```java\n// Using OWASP Java Encoder\nimport org.owasp.encoder.Encode;\n\n@Controller\npublic class UserController {\n @GetMapping(\"/profile\")\n public String showProfile(Model model, @RequestParam String username) {\n model.addAttribute(\"encodedUsername\", Encode.forHtml(username));\n return \"profile\";\n }\n}\n\n// In your template (e.g., Thymeleaf)\n// Username
\n```\n\n#### PHP\n\n```php\n// Using HTMLPurifier\nrequire_once 'HTMLPurifier.auto.php';\n\n$config = HTMLPurifier_Config::createDefault();\n$purifier = new HTMLPurifier($config);\n\n$userBio = $_POST['bio'];\n$cleanBio = $purifier->purify($userBio);\n\necho '' . $cleanBio . '
';\n```\n\n### Avoiding Dangerous Patterns\n\nCertain coding patterns are particularly vulnerable to XSS attacks:\n\n#### Avoid Unsafe JavaScript APIs\n\n```javascript\n// DANGEROUS - Never do this with user input\neval(userInput);\ndocument.write(userInput);\nnew Function(userInput);\nsetTimeout(userInput, 100);\nsetInterval(userInput, 100);\nelement.innerHTML = userInput;\n\n// SAFER ALTERNATIVES\n// Instead of eval, parse JSON safely\nconst data = JSON.parse(userInput);\n\n// Instead of innerHTML, use textContent\nelement.textContent = userInput;\n\n// Or create elements properly\nconst div = document.createElement('div');\ndiv.textContent = userInput;\nparentElement.appendChild(div);\n```\n\n#### Avoid Inline Scripts and Event Handlers\n\n```html\n\n\n\n\n\n\n```\n\n### Defense in Depth Strategy\n\nImplement multiple layers of protection:\n\n#### Content Security Policy (CSP)\n\n```http\n# Strong CSP header that blocks inline scripts and restricts sources\nContent-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'; style-src 'self'; img-src 'self' data:;\n```\n\n```javascript\n// Setting CSP in Express.js\nconst helmet = require('helmet');\napp.use(helmet.contentSecurityPolicy({\n directives: {\n defaultSrc: [\"'self'\"],\n scriptSrc: [\"'self'\", 'trusted-cdn.com'],\n objectSrc: [\"'none'\"],\n styleSrc: [\"'self'\"],\n imgSrc: [\"'self'\", 'data:']\n }\n}));\n```\n\n#### Secure Cookie Configuration\n\n```http\nSet-Cookie: sessionId=abc123; HttpOnly; Secure; SameSite=Strict\n```\n\n#### Input Validation\n\n```javascript\n// Validate input format before processing\nfunction validateUsername(username) {\n // Only allow alphanumeric characters and limited symbols\n const usernameRegex = /^[a-zA-Z0-9_.-]{3,30}$/;\n if (!usernameRegex.test(username)) {\n throw new Error('Invalid username format');\n }\n return username;\n}\n```"
},
{
"path": "sources/owasp/codeguard-0-zero-trust-architecture.md",
"content": "---\ndescription: Zero Trust Architecture Implementation - Security principles for designing\n systems with no implicit trust\nlanguages:\n- c\n- go\n- java\n- javascript\n- kotlin\n- php\n- python\n- ruby\n- scala\n- shell\n- swift\n- typescript\n- yaml\nalwaysApply: false\n---\n\n## Implementing Zero Trust Architecture\n\nImplementing Zero Trust Architecture (ZTA) principles in your applications is essential for modern security.\n\nZero Trust is built on the principle of \"never trust, always verify\" and assumes that threats exist both outside and inside the network. Key concepts include:\n\n- No implicit trust based on network location or asset ownership\n- Continuous verification of identity and device health\n- Least privilege access to resources and data\n- Microsegmentation of networks and applications\n- Continuous monitoring and analytics for threat detection\n\n### Authentication & Authorization\n\n- Implement Strong Authentication using FIDO2/WebAuthn\n\n- Implement Context-Aware Authorization\nImplement authorization that considers multiple factors:\n\n```java\n// Java example of context-aware authorization\npublic class ZeroTrustAuthorizationService {\n public boolean authorizeAccess(User user, Resource resource, AccessContext context) {\n // 1. Verify user identity\n if (!identityService.verifyIdentity(user)) {\n logFailedAttempt(\"Identity verification failed\", user, resource, context);\n return false;\n }\n\n // 2. Check device health and compliance\n if (!deviceService.isCompliant(context.getDeviceId())) {\n logFailedAttempt(\"Device not compliant\", user, resource, context);\n return false;\n }\n\n // 3. Evaluate risk score based on multiple factors\n int riskScore = riskEngine.calculateScore(user, resource, context);\n if (riskScore > ACCEPTABLE_THRESHOLD) {\n logFailedAttempt(\"Risk score too high\", user, resource, context);\n return false;\n }\n\n // 4. Check if user has required permissions\n if (!permissionService.hasPermission(user, resource, context.getRequestedAction())) {\n logFailedAttempt(\"Insufficient permissions\", user, resource, context);\n return false;\n }\n\n // 5. Log successful access\n auditLogger.logAccess(user, resource, context);\n return true;\n }\n}\n```\n\n- Implement Short-Lived Access Tokens\n\nImplement token-based authentication with short lifetimes:\n\n```python\n# Python example using JWT with short expiration\nimport jwt\nfrom datetime import datetime, timedelta\n\ndef generate_access_token(user_id, device_id, permissions):\n # Set token to expire in 15 minutes\n expiration = datetime.utcnow() + timedelta(minutes=15)\n\n payload = {\n 'sub': user_id,\n 'device_id': device_id,\n 'permissions': permissions,\n 'exp': expiration,\n 'iat': datetime.utcnow(),\n 'jti': str(uuid.uuid4()) # Unique token ID\n }\n\n # Sign with appropriate algorithm and key\n token = jwt.encode(payload, SECRET_KEY, algorithm='ES256')\n\n # Store token metadata for potential revocation\n store_token_metadata(user_id, payload['jti'], device_id, expiration)\n\n return token\n```\n\n### Secure Communication\n\n- Implement TLS 1.3 for all communications\n\n- Implement API security measures:\n\n```typescript\n// TypeScript example of API security middleware\nimport express from 'express';\nimport rateLimit from 'express-rate-limit';\nimport helmet from 'helmet';\n\nconst app = express();\n\n// Set security headers\napp.use(helmet());\n\n// Rate limiting\nconst apiLimiter = rateLimit({\n windowMs: 15 * 60 * 1000, // 15 minutes\n max: 100, // limit each IP to 100 requests per windowMs\n standardHeaders: true,\n legacyHeaders: false,\n});\napp.use('/api/', apiLimiter);\n\n// API authentication middleware\napp.use('/api/', (req, res, next) => {\n const token = req.headers.authorization?.split(' ')[1];\n\n if (!token) {\n return res.status(401).json({ error: 'Authentication required' });\n }\n\n try {\n // Verify token and extract user info\n const user = verifyAndDecodeToken(token);\n\n // Check if token has been revoked\n if (isTokenRevoked(token)) {\n return res.status(401).json({ error: 'Token revoked' });\n }\n\n // Add user info to request for downstream handlers\n req.user = user;\n next();\n } catch (error) {\n return res.status(401).json({ error: 'Invalid token' });\n }\n});\n\n// Payload validation middleware\napp.use(express.json({\n verify: (req, res, buf) => {\n try {\n // Check if JSON is valid and meets schema requirements\n validateSchema(buf.toString(), req.path);\n } catch (e) {\n throw new Error('Invalid JSON payload');\n }\n },\n limit: '100kb' // Limit payload size\n}));\n```\n\n### Monitoring and Logging\n\n- Implement Comprehensive Logging\n\n```csharp\n// C# example of detailed security logging\npublic class SecurityLogger\n{\n private readonly ILogger _logger;\n\n public SecurityLogger(ILogger logger)\n {\n _logger = logger;\n }\n\n public void LogAccessAttempt(string userId, string resourceId, bool success, AccessContext context)\n {\n var logEvent = new SecurityEvent\n {\n EventType = success ? \"access_granted\" : \"access_denied\",\n Timestamp = DateTime.UtcNow,\n UserId = userId,\n ResourceId = resourceId,\n IpAddress = context.IpAddress,\n DeviceId = context.DeviceId,\n DeviceHealth = context.DeviceHealthStatus,\n Location = context.GeoLocation,\n RequestedPermissions = context.RequestedPermissions,\n RiskScore = context.RiskScore\n };\n\n // Log with appropriate level\n if (success)\n {\n _logger.LogInformation(\"Access granted: {Event}\", JsonSerializer.Serialize(logEvent));\n }\n else\n {\n _logger.LogWarning(\"Access denied: {Event}\", JsonSerializer.Serialize(logEvent));\n }\n }\n}\n```\n\n### Implement fine-grained network and application segmentation\n\n\n```yaml\n# Kubernetes Network Policy example for microsegmentation\napiVersion: networking.k8s.io/v1\nkind: NetworkPolicy\nmetadata:\n name: api-backend-policy\n namespace: production\nspec:\n podSelector:\n matchLabels:\n app: api-backend\n policyTypes:\n - Ingress\n - Egress\n ingress:\n - from:\n - podSelector:\n matchLabels:\n app: frontend\n ports:\n - protocol: TCP\n port: 443\n egress:\n - to:\n - podSelector:\n matchLabels:\n app: database\n ports:\n - protocol: TCP\n port: 5432\n - to:\n - namespaceSelector:\n matchLabels:\n name: monitoring\n podSelector:\n matchLabels:\n app: telemetry\n ports:\n - protocol: TCP\n port: 9090\n```"
},
{
"path": "sources/templates/custom-rule-template.md.example",
"content": "---\ndescription: Brief description of the rule\nlanguages:\n- python\n- javascript\ntags:\n- data-security\nalwaysApply: false\n---\n\n\n\n## Rule Title\n\nBrief overview of what this rule enforces and why it matters.\n\n### Section Name\n- Guidance point with specific recommendation\n- Another specific requirement or best practice\n\n### Another Section\n- Additional guidance organized by topic\n- Keep points concise and actionable\n\n### Implementation Checklist\n- Verify requirement one is met\n- Confirm requirement two is implemented\n- Check that patterns are followed\n\n### Test Plan\n- Describe how to verify the rule is followed\n- Include specific test scenarios\n"
},
{
"path": "src/LICENSE.md",
"content": " Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n"
},
{
"path": "src/convert_to_ide_formats.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nConvert Unified Rules to IDE Formats\n\nTransforms the unified markdown sources into IDE-specific bundles (Cursor,\nWindsurf, Copilot, Agent Skills, Antigravity). This script is the main entry point\nfor producing distributable rule packs from the sources/ directory.\n\"\"\"\n\nimport re\nimport shutil\nfrom pathlib import Path\nfrom collections import defaultdict\n\nfrom converter import RuleConverter\nfrom formats import (\n CursorFormat,\n WindsurfFormat,\n CopilotFormat,\n AgentSkillsFormat,\n AntigravityFormat,\n)\nfrom utils import get_version_from_pyproject\nfrom validate_versions import set_plugin_version, set_marketplace_version\n\n# Project root is always one level up from src/\nPROJECT_ROOT = Path(__file__).parent.parent\n\n\ndef sync_plugin_metadata(version: str) -> None:\n \"\"\"\n Sync version from pyproject.toml to Agent Skills metadata files.\n\n Args:\n version: Version string from pyproject.toml\n \"\"\"\n set_plugin_version(version, PROJECT_ROOT)\n set_marketplace_version(version, PROJECT_ROOT)\n print(f\"✅ Synced plugin metadata to {version}\")\n\n\ndef matches_tag_filter(rule_tags: list[str], filter_tags: list[str]) -> bool:\n \"\"\"\n Check if rule has all required tags (AND logic).\n\n Args:\n rule_tags: List of tags from the rule (already normalized to lowercase)\n filter_tags: List of tags to filter by (already normalized to lowercase)\n\n Returns:\n True if rule has all filter tags (or no filter), False otherwise\n \"\"\"\n if not filter_tags:\n return True # No filter means all pass\n\n return all(tag in rule_tags for tag in filter_tags)\n\n\ndef update_skill_md(language_to_rules: dict[str, list[str]], skill_path: str) -> None:\n \"\"\"\n Update SKILL.md with language-to-rules mapping table.\n\n Args:\n language_to_rules: Dictionary mapping languages to rule files\n skill_path: Path to SKILL.md file\n \"\"\"\n # Generate markdown table\n table_lines = [\n \"| Language | Rule Files to Apply |\",\n \"|----------|---------------------|\",\n ]\n\n for language in sorted(language_to_rules.keys()):\n rules = sorted(language_to_rules[language])\n rules_str = \", \".join(rules)\n table_lines.append(f\"| {language} | {rules_str} |\")\n\n table = \"\\n\".join(table_lines)\n\n # Markers for the language mappings section\n start_marker = \"\"\n end_marker = \"\"\n\n # Read SKILL.md\n skill_file = Path(skill_path)\n content = skill_file.read_text(encoding=\"utf-8\")\n\n if start_marker not in content or end_marker not in content:\n raise RuntimeError(\n \"Invalid template: Language mappings section not found in codeguard-SKILLS.md.template\"\n )\n\n # Replace entire section including markers with just the table\n start_idx = content.index(start_marker)\n end_idx = content.index(end_marker) + len(end_marker)\n new_section = f\"\\n\\n{table}\\n\\n\"\n updated_content = content[:start_idx] + new_section + content[end_idx:]\n\n # Write back to SKILL.md\n skill_file.write_text(updated_content, encoding=\"utf-8\")\n print(f\"Updated SKILL.md with language mappings\")\n\n\ndef convert_rules(\n input_path: str,\n output_dir: str = \"dist\",\n include_agentskills: bool = True,\n version: str = None,\n filter_tags: list[str] = None,\n) -> dict[str, list[str]]:\n \"\"\"\n Convert rule file(s) to all supported IDE formats using RuleConverter.\n\n Args:\n input_path: Path to a single .md file or folder containing .md files\n output_dir: Output directory (default: 'dist/')\n include_agentskills: Whether to generate Agent Skills format (default: True, only for core rules)\n version: Version string to use (default: read from pyproject.toml)\n filter_tags: Optional list of tags to filter by (AND logic, case-insensitive)\n\n Returns:\n Dictionary with 'success' and 'errors' lists:\n {\n \"success\": [\"rule1.md\", \"rule2.md\"],\n \"errors\": [\"rule3.md: error message\"]\n }\n\n Example:\n results = convert_rules(\"sources/core\", \"dist\", include_agentskills=True)\n print(f\"Converted {len(results['success'])} rules\")\n \"\"\"\n if version is None:\n version = get_version_from_pyproject()\n\n # Specify formats to generate\n all_formats = [\n CursorFormat(version),\n WindsurfFormat(version),\n CopilotFormat(version),\n AntigravityFormat(version),\n ]\n\n # Only include Agent Skills format for core rules (committed as skills)\n if include_agentskills:\n all_formats.append(AgentSkillsFormat(version))\n\n converter = RuleConverter(formats=all_formats)\n path = Path(input_path)\n\n if not path.exists():\n raise FileNotFoundError(f\"{input_path} does not exist\")\n\n # Determine files to process\n if path.is_file():\n if path.suffix != \".md\":\n raise ValueError(f\"{input_path} is not a .md file\")\n md_files = [path]\n else:\n # Use rglob to recursively find all .md files in subdirectories\n md_files = sorted(list(path.rglob(\"*.md\")))\n if not md_files:\n raise ValueError(f\"No .md files found in {input_path}\")\n\n print(f\"Converting {len(md_files)} files from: {path}\")\n\n # Setup output directory\n output_base = Path(output_dir)\n\n results = {\"success\": [], \"errors\": [], \"skipped\": []}\n language_to_rules = defaultdict(list)\n\n # Process each file\n for md_file in md_files:\n try:\n # Convert the file (raises exceptions on error)\n result = converter.convert(md_file)\n\n # Apply tag filter if specified\n if filter_tags and not matches_tag_filter(result.tags, filter_tags):\n results[\"skipped\"].append(result.filename)\n continue\n\n # Write each format\n output_files = []\n for format_name, output in result.outputs.items():\n # Construct output path\n # Agent Skills goes to project root ./skills/\n # Other formats go to dist/ (or specified output_dir)\n if format_name == \"agentskills\":\n base_dir = PROJECT_ROOT\n else:\n base_dir = output_base\n\n output_file = (\n base_dir / output.subpath / f\"{result.basename}{output.extension}\"\n )\n\n # Create directory if it doesn't exist and write file\n output_file.parent.mkdir(parents=True, exist_ok=True)\n output_file.write_text(output.content, encoding=\"utf-8\")\n output_files.append(output_file.name)\n\n print(f\"Success: {result.filename} → {', '.join(output_files)}\")\n results[\"success\"].append(result.filename)\n\n # Update language mappings for SKILL.md\n for language in result.languages:\n language_to_rules[language].append(result.filename)\n\n except FileNotFoundError as e:\n error_msg = f\"{md_file.name}: File not found - {e}\"\n print(f\"Error: {error_msg}\")\n results[\"errors\"].append(error_msg)\n\n except ValueError as e:\n error_msg = f\"{md_file.name}: Validation error - {e}\"\n print(f\"Error: {error_msg}\")\n results[\"errors\"].append(error_msg)\n\n except Exception as e:\n error_msg = f\"{md_file.name}: Unexpected error - {e}\"\n print(f\"Error: {error_msg}\")\n results[\"errors\"].append(error_msg)\n\n # Summary\n if filter_tags:\n print(\n f\"\\nResults: {len(results['success'])} success, {len(results['skipped'])} skipped (tag filter), {len(results['errors'])} errors\"\n )\n else:\n print(\n f\"\\nResults: {len(results['success'])} success, {len(results['errors'])} errors\"\n )\n\n # Generate SKILL.md with language mappings (only if Agent Skills is included)\n if include_agentskills and language_to_rules:\n template_path = (\n PROJECT_ROOT / \"sources\" / \"core\" / \"codeguard-SKILLS.md.template\"\n )\n\n if not template_path.exists():\n raise FileNotFoundError(\n f\"SKILL.md template not found at {template_path}. \"\n \"This file is required for Agent Skills generation.\"\n )\n\n output_skill_dir = PROJECT_ROOT / \"skills\" / \"software-security\"\n output_skill_dir.mkdir(parents=True, exist_ok=True)\n output_skill_path = output_skill_dir / \"SKILL.md\"\n\n # Read template and inject current version from pyproject.toml\n template_content = template_path.read_text(encoding=\"utf-8\")\n # Replace the hardcoded version with actual version\n template_content = re.sub(\n r'codeguard-version:\\s*\"[^\"]*\"',\n f'codeguard-version: \"{version}\"',\n template_content,\n )\n output_skill_path.write_text(template_content, encoding=\"utf-8\")\n\n update_skill_md(language_to_rules, str(output_skill_path))\n\n return results\n\n\ndef _resolve_source_paths(args) -> list[Path]:\n \"\"\"\n Resolve source paths from CLI arguments.\n Priority: --source flags > default (core)\n \"\"\"\n # If --source flags provided, resolve under sources/\n if args.source:\n return [Path(\"sources\") / src for src in args.source]\n\n # Default: core rules only\n return [Path(\"sources/core\")]\n\n\nif __name__ == \"__main__\":\n import sys\n from argparse import ArgumentParser\n\n parser = ArgumentParser(\n description=\"Convert unified rule markdown into IDE-specific bundles.\"\n )\n parser.add_argument(\n \"--source\",\n nargs=\"+\",\n help=\"Named sources under ./sources to convert (e.g., --source core owasp). Default: core\",\n )\n parser.add_argument(\n \"--output-dir\",\n \"-o\",\n default=\"dist\",\n help=\"Output directory for generated bundles (default: dist).\",\n )\n parser.add_argument(\n \"--tag\",\n \"--tags\",\n dest=\"tags\",\n help=\"Filter rules by tags (comma-separated, case-insensitive, AND logic). Example: --tag api,web-security\",\n )\n\n cli_args = parser.parse_args()\n source_paths = _resolve_source_paths(cli_args)\n\n # Validate all source paths exist\n missing = [p for p in source_paths if not p.exists()]\n if missing:\n print(f\"❌ Source path(s) not found: {', '.join(str(p) for p in missing)}\")\n sys.exit(1)\n\n # Check for duplicate filenames across sources if multiple sources\n if len(source_paths) > 1:\n filename_to_sources = defaultdict(list)\n for source_path in source_paths:\n for md_file in source_path.rglob(\"*.md\"):\n filename_to_sources[md_file.name].append(source_path.name)\n\n duplicates = {\n name: srcs for name, srcs in filename_to_sources.items() if len(srcs) > 1\n }\n if duplicates:\n print(f\"❌ Found {len(duplicates)} duplicate filename(s) across sources:\")\n for filename, sources in duplicates.items():\n print(f\" - {filename} in: {', '.join(sources)}\")\n print(\"\\nPlease rename files to have unique names across all sources.\")\n sys.exit(1)\n\n # Get version once and sync to metadata files\n version = get_version_from_pyproject()\n sync_plugin_metadata(version)\n\n # Check if core is in the sources for Agent Skills generation\n has_core = Path(\"sources/core\") in source_paths\n if has_core:\n # Validate template exists early\n template_path = (\n PROJECT_ROOT / \"sources\" / \"core\" / \"codeguard-SKILLS.md.template\"\n )\n if not template_path.exists():\n print(f\"❌ SKILL.md template not found at {template_path}\")\n print(\"This file is required for Agent Skills generation.\")\n sys.exit(1)\n\n # Clean output directories once before processing\n output_path = Path(cli_args.output_dir)\n if output_path.exists():\n shutil.rmtree(output_path)\n print(f\"✅ Cleaned {cli_args.output_dir}/ directory\")\n\n if has_core:\n skills_rules_dir = PROJECT_ROOT / \"skills\" / \"software-security\" / \"rules\"\n if skills_rules_dir.exists():\n shutil.rmtree(skills_rules_dir)\n print(f\"✅ Cleaned skills/ directory\")\n\n # Print processing summary\n if len(source_paths) > 1:\n sources_list = \", \".join(p.name for p in source_paths)\n print(f\"\\nConverting {len(source_paths)} sources: {sources_list}\")\n if has_core:\n print(\"(Agent Skills will include only core rules)\")\n print()\n\n # Convert all sources\n aggregated = {\"success\": [], \"errors\": [], \"skipped\": []}\n # Parse comma-separated tags and normalize to lowercase\n filter_tags = None\n if cli_args.tags:\n filter_tags = [\n tag.strip().lower() for tag in cli_args.tags.split(\",\") if tag.strip()\n ]\n\n # Print tag filter info if active\n if filter_tags:\n print(\n f\"Tag filter active: {', '.join(filter_tags)} (AND logic - rules must have all tags)\\n\"\n )\n\n for source_path in source_paths:\n is_core = source_path == Path(\"sources/core\")\n\n print(f\"Processing: {source_path}\")\n results = convert_rules(\n str(source_path),\n cli_args.output_dir,\n include_agentskills=is_core,\n version=version,\n filter_tags=filter_tags,\n )\n\n aggregated[\"success\"].extend(results[\"success\"])\n aggregated[\"errors\"].extend(results[\"errors\"])\n if \"skipped\" in results:\n aggregated[\"skipped\"].extend(results[\"skipped\"])\n print(\"\")\n\n if aggregated[\"errors\"]:\n print(\"❌ Some conversions failed\")\n sys.exit(1)\n\n print(\"✅ All conversions successful\")\n"
},
{
"path": "src/converter.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nRule Converter\n\nConverts unified markdown rules to multiple IDE formats.\nHandles parsing, validation, and format generation.\n\"\"\"\nfrom dataclasses import dataclass\nfrom pathlib import Path\n\nfrom language_mappings import languages_to_globs\nfrom utils import parse_frontmatter_and_content, validate_tags\nfrom formats import (\n BaseFormat,\n ProcessedRule,\n)\n\n\n@dataclass\nclass FormatOutput:\n \"\"\"\n Represents the output for a single format.\n\n Attributes:\n content: The fully formatted content with frontmatter\n extension: File extension including dot (e.g., '.mdc')\n subpath: Subdirectory path (e.g., '.cursor/rules', 'skills/software-security/rules')\n \"\"\"\n\n content: str\n extension: str\n subpath: str\n\n\n@dataclass\nclass ConversionResult:\n \"\"\"\n Represents the complete result of converting a rule file.\n\n Attributes:\n filename: Original filename (e.g., 'my-rule.md')\n basename: Filename without extension (e.g., 'my-rule')\n outputs: Dictionary mapping format names to their outputs\n languages: List of programming languages the rule applies to, empty list if always applies\n tags: List of tags for categorizing and filtering rules\n Example:\n result = ConversionResult(\n filename=\"my-rule.md\",\n basename=\"my-rule\",\n outputs={\n \"cursor\": FormatOutput(\n content=\"---\\\\n...\\\\n---\\\\n\\\\nContent\",\n extension=\".mdc\",\n subpath=\".cursor/rules\"\n )\n },\n languages=[\"python\", \"javascript\"],\n tags=[\"authentication\", \"web-security\"]\n )\n \"\"\"\n\n filename: str\n basename: str\n outputs: dict[str, FormatOutput]\n languages: list[str]\n tags: list[str]\n\n\nclass RuleConverter:\n \"\"\"\n Converts markdown rules to multiple IDE formats.\n\n Uses the BaseFormat abstraction to support multiple IDE formats in an extensible way.\n New formats can be added by creating a new BaseFormat subclass and passing it to the converter.\n\n Main Methods:\n - parse_rule(): Parse markdown file with YAML frontmatter\n - generate_globs(): Convert languages to glob patterns\n - convert(): Convert a rule file to all registered formats (returns ConversionResult)\n\n Example:\n # Create converter\n from converter import RuleConverter, ConversionResult, FormatOutput\n from formats import CursorFormat, WindsurfFormat\n from utils import get_version_from_pyproject\n\n version = get_version_from_pyproject()\n converter = RuleConverter(formats=[\n CursorFormat(version),\n WindsurfFormat(version)\n ])\n\n # Convert a file\n try:\n result = converter.convert(\"rule.md\")\n # result is ConversionResult dataclass\n\n for format_name, output in result.outputs.items():\n # output is FormatOutput dataclass\n print(f\"{format_name}: {output.extension}\")\n save_file(output.content, output.subpath)\n except ValueError as e:\n print(f\"Invalid rule: {e}\")\n \"\"\"\n\n def __init__(self, formats: list[BaseFormat]):\n \"\"\"\n Initialize the converter with version info and supported formats.\n\n Args:\n formats: List of BaseFormat instances to use for conversion.\n \"\"\"\n self.formats = formats\n\n def parse_rule(self, content: str, filename: str) -> ProcessedRule:\n \"\"\"\n Parse a markdown file with required frontmatter.\n\n Args:\n content: Full file content with YAML frontmatter\n filename: Name of the file being parsed\n\n Returns:\n ProcessedRule with validated frontmatter and content\n\n Raises:\n ValueError: If frontmatter is missing or invalid\n \"\"\"\n # Parse frontmatter and content using shared utility\n frontmatter, markdown_content = parse_frontmatter_and_content(content)\n\n if not frontmatter:\n raise ValueError(f\"Missing or invalid frontmatter in {filename}\")\n\n # Validate required description field\n if \"description\" not in frontmatter or not frontmatter[\"description\"].strip():\n raise ValueError(f\"Missing required 'description' field in {filename}\")\n\n always_apply = frontmatter.get(\"alwaysApply\", False)\n\n # Validate languages field based on alwaysApply setting\n if always_apply:\n # If alwaysApply is true, languages should not be specified or should be empty\n if \"languages\" in frontmatter and frontmatter[\"languages\"]:\n raise ValueError(\n f\"When 'alwaysApply' is true, 'languages' should not be specified or should be empty in {filename}\"\n )\n languages = [] # No languages when always applying\n else:\n # If alwaysApply is false, languages is required\n if \"languages\" not in frontmatter:\n raise ValueError(\n f\"Missing required 'languages' field in {filename} (required when alwaysApply is false)\"\n )\n\n languages = frontmatter[\"languages\"]\n if not isinstance(languages, list) or not languages:\n raise ValueError(\n f\"'languages' must be a non-empty list in {filename} when alwaysApply is false\"\n )\n\n # Parse and validate tags (optional field)\n tags = []\n if \"tags\" in frontmatter:\n tags = validate_tags(frontmatter[\"tags\"], filename)\n\n # Adding rule_id to the beginning of the content\n rule_id = Path(filename).stem\n markdown_content = f\"rule_id: {rule_id}\\n\\n{markdown_content}\"\n\n return ProcessedRule(\n description=frontmatter[\"description\"],\n languages=[lang.lower() for lang in languages],\n always_apply=always_apply,\n content=markdown_content,\n filename=filename,\n tags=tags,\n )\n\n def generate_globs(self, languages: list[str]) -> str:\n \"\"\"\n Generate comma-separated glob patterns for languages.\n\n Args:\n languages: List of programming languages\n\n Returns:\n Comma-separated glob patterns, or \"**/*\" for all files\n \"\"\"\n # Use shared function from language_mappings\n globs = languages_to_globs(languages)\n return globs if globs else \"**/*\"\n\n def convert(self, filepath: str) -> ConversionResult:\n \"\"\"\n Convert a rule file to all registered formats.\n\n This method handles the entire conversion pipeline:\n - Reading the file\n - Parsing and validating\n - Generating all format outputs\n\n Args:\n filepath: Path to the rule file to convert (str or Path)\n\n Returns:\n ConversionResult with filename, basename, and format outputs\n\n Raises:\n FileNotFoundError: If the rule file doesn't exist\n ValueError: If the rule has invalid frontmatter or structure\n Exception: For other unexpected errors during conversion\n\n Example:\n try:\n result = converter.convert(\"rules/my-rule.md\")\n for format_name, output in result.outputs.items():\n path = f\"{output.subpath}/{result.basename}{output.extension}\"\n write_file(path, output.content)\n except (FileNotFoundError, ValueError) as e:\n print(f\"Error: {e}\")\n \"\"\"\n filepath = Path(filepath)\n filename = filepath.name\n basename = filepath.stem\n\n # Read the rule file (may raise FileNotFoundError)\n content = filepath.read_text(encoding=\"utf-8\")\n\n # Parse and validate (may raise ValueError)\n rule = self.parse_rule(content, filename)\n\n # Generate globs once for all formats\n globs = self.generate_globs(rule.languages)\n\n # Generate output for each format\n outputs = {}\n for format_handler in self.formats:\n format_name = format_handler.get_format_name()\n outputs[format_name] = FormatOutput(\n content=format_handler.generate(rule, globs),\n extension=format_handler.get_file_extension(),\n subpath=format_handler.get_output_subpath(),\n )\n\n return ConversionResult(\n filename=filename,\n basename=basename,\n outputs=outputs,\n languages=rule.languages,\n tags=rule.tags,\n )\n"
},
{
"path": "src/formats/__init__.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nFormats Package\n\nThis package contains all IDE format implementations for rule conversion.\n\nAvailable Formats:\n- CursorFormat: Generates .mdc files for Cursor IDE\n- WindsurfFormat: Generates .md files for Windsurf IDE\n- CopilotFormat: Generates .instructions.md files for GitHub Copilot\n- AgentSkillsFormat: Generates .md files for Agent Skills (OpenAI Codex, Claude Code, other AI coding tools)\n- AntigravityFormat: Generates .md files for Google Antigravity\n\nUsage:\n from formats import BaseFormat, ProcessedRule, CursorFormat, WindsurfFormat, CopilotFormat, AgentSkillsFormat, AntigravityFormat\n\n version = \"1.0.0\"\n formats = [\n CursorFormat(version),\n WindsurfFormat(version),\n CopilotFormat(version),\n AgentSkillsFormat(version),\n AntigravityFormat(version),\n ]\n\"\"\"\n\nfrom formats.base import BaseFormat, ProcessedRule\nfrom formats.cursor import CursorFormat\nfrom formats.windsurf import WindsurfFormat\nfrom formats.copilot import CopilotFormat\nfrom formats.agentskills import AgentSkillsFormat\nfrom formats.antigravity import AntigravityFormat\n\n__all__ = [\n \"BaseFormat\",\n \"ProcessedRule\",\n \"CursorFormat\",\n \"WindsurfFormat\",\n \"CopilotFormat\",\n \"AgentSkillsFormat\",\n \"AntigravityFormat\",\n]\n"
},
{
"path": "src/formats/agentskills.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nAgent Skills Format Implementation\n\nGenerates .md files for the Agent Skills standard (agentskills.io).\nThis format is used by OpenAI Codex, Claude Code, and other AI coding tools.\n\"\"\"\n\nfrom formats.base import BaseFormat, ProcessedRule\n\n\nclass AgentSkillsFormat(BaseFormat):\n \"\"\"\n Agent Skills format implementation (.md files).\n\n Agent Skills (https://agentskills.io/) is an open standard for extending\n AI coding agents with task-specific capabilities. It uses standard markdown\n files with YAML frontmatter to define rules and instructions.\n\n This format is adopted by:\n - OpenAI Codex (skills)\n - Claude Code (plugins)\n - Other AI coding tools\n\n The original rule content is preserved and placed in the\n skills/software-security/rules/ directory for distribution.\n \"\"\"\n\n def get_format_name(self) -> str:\n \"\"\"Return Agent Skills format identifier.\"\"\"\n return \"agentskills\"\n\n def get_file_extension(self) -> str:\n \"\"\"Return Agent Skills format file extension.\"\"\"\n return \".md\"\n\n def get_output_subpath(self) -> str:\n \"\"\"Return Agent Skills output subdirectory.\"\"\"\n return \"skills/software-security/rules\"\n\n def generate(self, rule: ProcessedRule, globs: str) -> str:\n \"\"\"\n Generate Agent Skills .md format.\n\n Agent Skills should preserve the original YAML frontmatter\n (description, languages, alwaysApply) so the rules remain complete\n and can be referenced properly by AI coding agents.\n\n Args:\n rule: The processed rule to format\n globs: Glob patterns (not used for Agent Skills format)\n\n Returns:\n Complete markdown with original YAML frontmatter preserved\n \"\"\"\n # Build YAML frontmatter\n yaml_lines = []\n\n # Add description\n desc = self._format_yaml_field(\"description\", rule.description)\n if desc:\n yaml_lines.append(desc)\n\n # Add languages if present\n if rule.languages:\n # Format as YAML list\n yaml_lines.append(\"languages:\")\n for lang in rule.languages:\n yaml_lines.append(f\"- {lang}\")\n\n # Add alwaysApply\n yaml_lines.append(f\"alwaysApply: {str(rule.always_apply).lower()}\")\n\n return self._build_yaml_frontmatter(yaml_lines, rule.content)\n"
},
{
"path": "src/formats/antigravity.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nAntigravity Format Implementation\n\nGenerates .md rule files for Antigravity with YAML frontmatter.\n\"\"\"\n\nfrom formats.base import BaseFormat, ProcessedRule\n\n\nclass AntigravityFormat(BaseFormat):\n \"\"\"\n Antigravity format implementation (.md rule files).\n\n Antigravity uses .md files with YAML frontmatter containing:\n - trigger: 'always_on' or 'glob' (activation type)\n - globs: (if trigger is 'glob') File matching patterns\n - description: Rule description\n - version: Rule version\n \n Rules use activation types (Always On or Glob) to determine when\n they apply, similar to Windsurf's implementation.\n See: https://antigravity.google/docs/rules-workflows\n \"\"\"\n\n def get_format_name(self) -> str:\n \"\"\"Return Antigravity format identifier.\"\"\"\n return \"antigravity\"\n\n def get_file_extension(self) -> str:\n \"\"\"Return Antigravity format file extension.\"\"\"\n return \".md\"\n\n def get_output_subpath(self) -> str:\n \"\"\"Return Antigravity output subdirectory.\"\"\"\n return \".agent/rules\"\n\n def generate(self, rule: ProcessedRule, globs: str) -> str:\n \"\"\"\n Generate Antigravity .md format with YAML frontmatter.\n\n Args:\n rule: The processed rule to format\n globs: Glob patterns for file matching\n\n Returns:\n Formatted .md content with trigger, globs, description, and version\n \n Note:\n Antigravity rules use activation types:\n - 'always_on': Rule applies to all files (when alwaysApply is true)\n - 'glob': Rule applies to files matching glob patterns (language-specific)\n \"\"\"\n yaml_lines = []\n\n # Use trigger: always_on for rules that should always apply\n if rule.always_apply:\n yaml_lines.append(\"trigger: always_on\")\n else:\n yaml_lines.append(\"trigger: glob\")\n yaml_lines.append(f\"globs: {globs}\")\n\n # Add description (required by Antigravity spec)\n desc = self._format_yaml_field(\"description\", rule.description)\n if desc:\n yaml_lines.append(desc)\n\n # Add version\n yaml_lines.append(f\"version: {self.version}\")\n\n return self._build_yaml_frontmatter(yaml_lines, rule.content)\n"
},
{
"path": "src/formats/base.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nBase Format Class\n\nAbstract base class for all IDE rule formats.\nDefines the interface that all format implementations must follow.\n\"\"\"\n\nimport yaml\nfrom abc import ABC, abstractmethod\nfrom dataclasses import dataclass\n\n\n@dataclass\nclass ProcessedRule:\n \"\"\"\n Represents a processed rule with required frontmatter.\n\n Attributes:\n description: Human-readable description of the rule\n languages: List of programming languages this rule applies to\n always_apply: Whether this rule should apply to all files\n content: The actual rule content in markdown format\n filename: Original filename of the rule\n tags: List of tags for categorizing and filtering rules\n \"\"\"\n\n description: str\n languages: list[str]\n always_apply: bool\n content: str\n filename: str\n tags: list[str]\n\n\nclass BaseFormat(ABC):\n \"\"\"\n Abstract base class for IDE rule formats.\n\n This class defines the interface that all format implementations must follow.\n Each format is responsible for:\n - Providing its file extension (e.g., '.mdc', '.md')\n - Providing its output subdirectory path (e.g., '.cursor/rules')\n - Generating formatted content with proper frontmatter\n \"\"\"\n\n def __init__(self, version: str):\n \"\"\"\n Initialize format with version information.\n\n Args:\n version: Version string to include in generated files\n \"\"\"\n self.version = version\n\n @abstractmethod\n def get_format_name(self) -> str:\n \"\"\"\n Return the unique identifier for this format.\n\n Returns:\n Format name (e.g., 'cursor', 'windsurf', 'copilot')\n \"\"\"\n pass\n\n @abstractmethod\n def get_file_extension(self) -> str:\n \"\"\"\n Return the file extension for this format.\n\n Returns:\n File extension including the dot (e.g., '.mdc', '.md')\n \"\"\"\n pass\n\n @abstractmethod\n def get_output_subpath(self) -> str:\n \"\"\"\n Return the subdirectory path for this format.\n\n Returns:\n Subdirectory path (e.g., '.cursor/rules', 'skills/software-security/rules')\n \"\"\"\n pass\n\n @abstractmethod\n def generate(self, rule: ProcessedRule, globs: str) -> str:\n \"\"\"\n Generate the formatted content for this IDE format.\n\n Args:\n rule: The processed rule to format\n globs: Glob patterns for file matching\n\n Returns:\n Fully formatted content with frontmatter and rule content\n \"\"\"\n pass\n\n def _build_yaml_frontmatter(self, lines: list[str], content: str) -> str:\n \"\"\"\n Helper to build complete file with YAML frontmatter.\n\n Args:\n lines: List of YAML lines to include in frontmatter\n content: The markdown content to append after frontmatter\n\n Returns:\n Complete formatted string with frontmatter and content\n \"\"\"\n yaml_str = \"\\n\".join(lines)\n return f\"---\\n{yaml_str}\\n---\\n\\n{content}\\n\"\n\n def _format_yaml_field(self, field_name: str, value: str) -> str:\n \"\"\"\n Format a field with proper YAML escaping for special characters.\n\n Args:\n field_name: Name of the YAML field\n value: Value to format\n\n Returns:\n Properly formatted YAML string, or empty string if value is empty\n \"\"\"\n if value and value.strip():\n yaml_dump = yaml.safe_dump(\n {field_name: value},\n default_flow_style=False,\n allow_unicode=True,\n width=float(\"inf\")\n )\n return yaml_dump.strip()\n return \"\"\n"
},
{
"path": "src/formats/copilot.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nCopilot Format Implementation\n\nGenerates .instructions.md files for GitHub Copilot with YAML frontmatter.\n\"\"\"\n\nfrom formats.base import BaseFormat, ProcessedRule\n\n\nclass CopilotFormat(BaseFormat):\n \"\"\"\n GitHub Copilot format implementation (.instructions.md files).\n\n Copilot uses .instructions.md files with YAML frontmatter containing:\n - applyTo: File matching patterns\n - title: Rule title/description\n - version: Rule version\n \"\"\"\n\n def get_format_name(self) -> str:\n \"\"\"Return Copilot format identifier.\"\"\"\n return \"copilot\"\n\n def get_file_extension(self) -> str:\n \"\"\"Return Copilot format file extension.\"\"\"\n return \".instructions.md\"\n\n def get_output_subpath(self) -> str:\n \"\"\"Return Copilot output subdirectory.\"\"\"\n return \".github/instructions\"\n\n def generate(self, rule: ProcessedRule, globs: str) -> str:\n \"\"\"\n Generate Copilot .instructions.md format with YAML frontmatter.\n\n Args:\n rule: The processed rule to format\n globs: Glob patterns for file matching\n\n Returns:\n Formatted .instructions.md content\n \"\"\"\n yaml_lines = []\n\n # Add applyTo (Copilot's equivalent of globs)\n yaml_lines.append(f\"applyTo: '{globs}'\")\n\n # Add description\n description = self._format_yaml_field(\"description\", rule.description)\n if description:\n yaml_lines.append(description)\n\n # Add version\n yaml_lines.append(f\"version: {self.version}\")\n\n return self._build_yaml_frontmatter(yaml_lines, rule.content)\n"
},
{
"path": "src/formats/cursor.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nCursor Format Implementation\n\nGenerates .mdc files for Cursor IDE with YAML frontmatter.\n\"\"\"\n\nfrom formats.base import BaseFormat, ProcessedRule\n\n\nclass CursorFormat(BaseFormat):\n \"\"\"\n Cursor IDE format implementation (.mdc files).\n\n Cursor uses .mdc files with YAML frontmatter containing:\n - description: Rule description\n - globs: File matching patterns\n - version: Rule version\n - alwaysApply: (optional) Whether to apply to all files\n \"\"\"\n\n def get_format_name(self) -> str:\n \"\"\"Return Cursor format identifier.\"\"\"\n return \"cursor\"\n\n def get_file_extension(self) -> str:\n \"\"\"Return Cursor format file extension.\"\"\"\n return \".mdc\"\n\n def get_output_subpath(self) -> str:\n \"\"\"Return Cursor output subdirectory.\"\"\"\n return \".cursor/rules\"\n\n def generate(self, rule: ProcessedRule, globs: str) -> str:\n \"\"\"\n Generate Cursor .mdc format with YAML frontmatter.\n\n Args:\n rule: The processed rule to format\n globs: Glob patterns for file matching\n\n Returns:\n Formatted .mdc content\n \"\"\"\n yaml_lines = []\n\n # Add description if present\n desc = self._format_yaml_field(\"description\", rule.description)\n if desc:\n yaml_lines.append(desc)\n\n # Add globs and version\n yaml_lines.append(f\"globs: {globs}\")\n yaml_lines.append(f\"version: {self.version}\")\n\n # Add alwaysApply if needed\n if rule.always_apply:\n yaml_lines.append(\"alwaysApply: true\")\n\n return self._build_yaml_frontmatter(yaml_lines, rule.content)\n"
},
{
"path": "src/formats/windsurf.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nWindsurf Format Implementation\n\nGenerates .md files for Windsurf IDE with YAML frontmatter.\n\"\"\"\n\nfrom formats.base import BaseFormat, ProcessedRule\n\n\nclass WindsurfFormat(BaseFormat):\n \"\"\"\n Windsurf IDE format implementation (.md files).\n\n Windsurf uses .md files with YAML frontmatter containing:\n - trigger: 'always_on' or 'glob'\n - globs: (if trigger is 'glob') File matching patterns\n - title: Rule title/description\n - version: Rule version\n \"\"\"\n\n def get_format_name(self) -> str:\n \"\"\"Return Windsurf format identifier.\"\"\"\n return \"windsurf\"\n\n def get_file_extension(self) -> str:\n \"\"\"Return Windsurf format file extension.\"\"\"\n return \".md\"\n\n def get_output_subpath(self) -> str:\n \"\"\"Return Windsurf output subdirectory.\"\"\"\n return \".windsurf/rules\"\n\n def generate(self, rule: ProcessedRule, globs: str) -> str:\n \"\"\"\n Generate Windsurf .md format with YAML frontmatter.\n\n Args:\n rule: The processed rule to format\n globs: Glob patterns for file matching\n\n Returns:\n Formatted .md content\n \"\"\"\n yaml_lines = []\n\n # Use trigger: always_on for rules that should always apply\n if rule.always_apply:\n yaml_lines.append(\"trigger: always_on\")\n else:\n yaml_lines.append(\"trigger: glob\")\n yaml_lines.append(f\"globs: {globs}\")\n\n # Add title (Windsurf uses 'title' instead of 'description')\n title = self._format_yaml_field(\"title\", rule.description)\n if title:\n yaml_lines.append(title)\n\n # Add version\n yaml_lines.append(f\"version: {self.version}\")\n\n return self._build_yaml_frontmatter(yaml_lines, rule.content)\n"
},
{
"path": "src/language_mappings.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nShared language mappings for all rule tools.\nSingle source of truth for language-to-extension mappings.\n\"\"\"\n\n# Master mapping of languages to file extensions\nLANGUAGE_TO_EXTENSIONS = {\n \"apex\": [\".cls\", \".trigger\"],\n \"python\": [\".py\", \".pyx\", \".pyi\"],\n \"javascript\": [\".js\", \".jsx\", \".mjs\"],\n \"typescript\": [\".ts\", \".tsx\"],\n \"java\": [\".java\"],\n \"c\": [\".c\", \".h\"],\n \"cpp\": [\".cpp\", \".hpp\", \".cc\", \".cxx\"],\n \"c++\": [\".cpp\", \".hpp\", \".cc\", \".cxx\"], # Alias\n \"go\": [\".go\"],\n \"rust\": [\".rs\"],\n \"ruby\": [\".rb\"],\n \"php\": [\".php\"],\n \"swift\": [\".swift\"],\n \"kotlin\": [\".kt\", \".kts\"],\n \"scala\": [\".scala\"],\n \"r\": [\".r\", \".R\"],\n \"matlab\": [\".m\"],\n \"julia\": [\".jl\"],\n \"dart\": [\".dart\"],\n \"lua\": [\".lua\"],\n \"perl\": [\".pl\", \".pm\"],\n \"shell\": [\".sh\", \".bash\"],\n \"powershell\": [\".ps1\"],\n \"fsharp\": [\".fs\", \".fsx\"],\n \"clojure\": [\".clj\", \".cljs\"],\n \"elixir\": [\".ex\", \".exs\"],\n \"erlang\": [\".erl\", \".hrl\"],\n \"ocaml\": [\".ml\", \".mli\"],\n \"nim\": [\".nim\"],\n \"vlang\": [\".v\"],\n \"zig\": [\".zig\"],\n \"d\": [\".d\"],\n \"solidity\": [\".sol\"],\n \"vyper\": [\".vy\"],\n \"cairo\": [\".cairo\"],\n \"sway\": [\".sway\"],\n \"handlebars\": [\".hbs\"],\n \"liquid\": [\".liquid\"],\n \"markdown\": [\".md\"],\n \"mdx\": [\".mdx\"],\n \"latex\": [\".tex\"],\n \"yaml\": [\".yml\", \".yaml\"],\n \"docker\": [\"Dockerfile*\", \"docker-compose*\", \".dockerfile\"],\n \"xml\": [\".xml\", \".xsd\", \".xslt\", \".wsdl\"],\n \"vue\": [\".vue\"],\n \"svelte\": [\".svelte\"],\n \"astro\": [\".astro\"],\n \"elm\": [\".elm\"],\n \"purescript\": [\".purs\"],\n \"idris\": [\".idr\"],\n \"agda\": [\".agda\"],\n \"lean\": [\".lean\"],\n \"coq\": [\".coq\"],\n \"verilog\": [\".v\"],\n \"vhdl\": [\".vhd\", \".vhdl\"],\n \"cuda\": [\".cu\", \".cuh\"],\n \"opencl\": [\".cl\"],\n \"glsl\": [\".glsl\", \".vert\", \".frag\"],\n \"hlsl\": [\".hlsl\"],\n \"wgsl\": [\".wgsl\"],\n \"html\": [\".html\", \".htm\"],\n \"sql\": [\".sql\", \".ddl\", \".dml\"],\n}\n\n# Reverse mapping: extension to language (for conversion from globs)\nEXTENSION_TO_LANGUAGE = {}\nfor lang, exts in LANGUAGE_TO_EXTENSIONS.items():\n for ext in exts:\n # First language wins for duplicate extensions\n if ext not in EXTENSION_TO_LANGUAGE:\n EXTENSION_TO_LANGUAGE[ext] = lang\n\n\ndef languages_to_globs(languages: list[str]) -> str:\n \"\"\"\n Convert list of languages to glob patterns.\n \n Args:\n languages: List of programming language names (e.g., ['python', 'javascript'])\n \n Returns:\n Comma-separated glob patterns (e.g., '**/*.py,**/*.js')\n Empty string if no languages provided\n \"\"\"\n if not languages:\n return \"\"\n\n extensions = []\n for lang in languages:\n if lang in LANGUAGE_TO_EXTENSIONS:\n for ext in LANGUAGE_TO_EXTENSIONS[lang]:\n if \"*\" in ext:\n extensions.append(ext)\n else:\n extensions.append(f\"**/*{ext}\")\n\n return \",\".join(sorted(set(extensions)))\n\n\ndef globs_to_languages(globs: str) -> list[str]:\n \"\"\"\n Convert glob patterns to list of languages.\n \n Args:\n globs: Comma-separated glob patterns (e.g., '**/*.py,**/*.js')\n \n Returns:\n Sorted list of language names that match the glob patterns\n Empty list if no patterns or universal glob provided\n \"\"\"\n if not globs or globs in [\"**\", \"*\", \"**/*\"]:\n return []\n\n languages = set()\n patterns = globs.split(\",\")\n\n for pattern in patterns:\n pattern = pattern.strip().lower()\n\n # Check for file extensions and patterns\n for ext, lang in EXTENSION_TO_LANGUAGE.items():\n if ext.lower() in pattern:\n languages.add(lang)\n break # One match per pattern is enough\n\n return sorted(languages)\n"
},
{
"path": "src/tag_mappings.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nTag Mappings\n\nCentralized list of known tags for categorizing security rules.\n\"\"\"\n\n# Known tags used in rules\n# Add new tags here as they are introduced in rules\nKNOWN_TAGS = {\n \"authentication\",\n \"data-security\",\n \"infrastructure\",\n \"privacy\",\n \"secrets\",\n \"web\",\n}\n\n"
},
{
"path": "src/utils.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nUtilities for rule processing.\n\nCommon utilities used across the rule conversion tools.\n\"\"\"\n\nimport re\nimport tomllib\nfrom pathlib import Path\nimport yaml\n\n\ndef parse_frontmatter_and_content(content: str) -> tuple[dict | None, str]:\n \"\"\"\n Parse YAML frontmatter and content from markdown.\n \n Frontmatter must be in the format:\n ---\n yaml content\n ---\n markdown content\n \n The closing --- must be on its own line (not part of a comment or text).\n\n Args:\n content: Full file content\n\n Returns:\n Tuple of (frontmatter dict, markdown content)\n Returns (None, content) if no valid frontmatter found\n \"\"\"\n if not content.startswith(\"---\\n\"):\n return None, content\n\n # Look for closing --- on its own line\n # Use regex to ensure --- is at start of line (after newline)\n closing_pattern = re.compile(r'\\n---\\n')\n match = closing_pattern.search(content)\n \n if not match:\n # No proper closing ---, treat as no frontmatter\n return None, content\n \n # Extract frontmatter between opening and closing ---\n frontmatter_text = content[4:match.start()] # Skip opening \"---\\n\"\n markdown_content = content[match.end():] # Skip closing \"---\\n\"\n\n try:\n frontmatter = yaml.safe_load(frontmatter_text)\n except yaml.YAMLError:\n return None, content\n\n return frontmatter, markdown_content.strip()\n\n\ndef validate_tags(tags, filename=None) -> list[str]:\n \"\"\"\n Validate tags list and return normalized (lowercase) tags.\n \n Args:\n tags: The tags value to validate (should be a non-empty list)\n filename: Optional filename for better error messages\n \n Returns:\n List of normalized (lowercase) tags with duplicates removed.\n Original order is preserved.\n \n Raises:\n ValueError: If tags are invalid (wrong type, empty list, contain whitespace, etc.)\n \n Note:\n - An empty tags list (tags: []) is considered invalid. If you have no tags,\n omit the 'tags' field entirely from the frontmatter.\n - Duplicate tags (after normalization) are automatically removed while\n preserving the order of first occurrence.\n \"\"\"\n context = f\" in {filename}\" if filename else \"\"\n \n if not isinstance(tags, list):\n raise ValueError(f\"'tags' must be a list{context}\")\n \n if not tags:\n raise ValueError(f\"'tags' list cannot be empty{context}. Omit the field if you have no tags.\")\n \n normalized = []\n for tag in tags:\n if not isinstance(tag, str):\n raise ValueError(f\"All tags must be strings{context}, found: {type(tag).__name__}\")\n \n if any(c.isspace() for c in tag):\n raise ValueError(f\"Tags cannot contain whitespace: '{tag}'{context}\")\n \n if not tag:\n raise ValueError(f\"Empty tag found{context}\")\n \n normalized.append(tag.lower())\n \n return list(dict.fromkeys(normalized))\n\n\ndef get_version_from_pyproject() -> str:\n \"\"\"\n Read version from pyproject.toml using Python's built-in TOML parser.\n\n Requires Python 3.11+ for tomllib support.\n\n Returns:\n Version string from pyproject.toml\n\n Raises:\n FileNotFoundError: If pyproject.toml is not found\n ValueError: If version field is missing or invalid\n \"\"\"\n pyproject_path = Path(\"pyproject.toml\")\n\n if not pyproject_path.exists():\n raise FileNotFoundError(\"pyproject.toml not found\")\n\n try:\n with open(pyproject_path, \"rb\") as f:\n data = tomllib.load(f)\n\n if \"project\" in data and \"version\" in data[\"project\"]:\n version = data[\"project\"][\"version\"]\n if isinstance(version, str) and version.strip():\n return version.strip()\n raise ValueError(\"Version field not found in pyproject.toml [project] section\")\n except tomllib.TOMLDecodeError as e:\n raise ValueError(f\"Invalid TOML syntax in pyproject.toml: {str(e)}\")\n except (FileNotFoundError, ValueError):\n raise\n except Exception as e:\n raise ValueError(f\"Unexpected error reading pyproject.toml: {str(e)}\")\n"
},
{
"path": "src/validate_unified_rules.py",
"content": "# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nValidate Unified Rules Format\n\nValidates that unified rules have correct YAML frontmatter and structure.\n\"\"\"\n\nimport sys\nfrom pathlib import Path\n\nfrom language_mappings import LANGUAGE_TO_EXTENSIONS\nfrom tag_mappings import KNOWN_TAGS\nfrom utils import parse_frontmatter_and_content, validate_tags\n\n\ndef validate_rule(file_path: Path) -> dict[str, list[str]]:\n \"\"\"Validate a single unified rule file.\"\"\"\n errors = []\n warnings = []\n\n try:\n # Read and parse file\n content = file_path.read_text(encoding=\"utf-8\")\n frontmatter, markdown_content = parse_frontmatter_and_content(content)\n\n if frontmatter is None:\n errors.append(\"Missing or invalid YAML frontmatter\")\n return {\"errors\": errors, \"warnings\": warnings}\n\n # Check required fields\n if \"description\" not in frontmatter:\n errors.append(\"Missing required field: description\")\n elif not str(frontmatter[\"description\"]).strip():\n errors.append(\"description cannot be empty\")\n\n # Validate languages and alwaysApply logic\n has_languages = \"languages\" in frontmatter and frontmatter[\"languages\"]\n always_apply = frontmatter.get(\"alwaysApply\", False)\n\n if always_apply and has_languages:\n errors.append(\"Rules with alwaysApply=true should not have languages\")\n elif not always_apply and not has_languages:\n errors.append(\"Rules must have either languages or alwaysApply=true\")\n\n # Validate language names if present\n if has_languages and isinstance(frontmatter[\"languages\"], list):\n unknown = [\n lang\n for lang in frontmatter[\"languages\"]\n if lang.lower() not in LANGUAGE_TO_EXTENSIONS\n ]\n if unknown:\n warnings.append(f\"Unknown languages: {', '.join(unknown)}\")\n\n # Validate tags if present\n if \"tags\" in frontmatter:\n try:\n normalized_tags = validate_tags(frontmatter[\"tags\"], file_path.name)\n # Error on tags not in known list\n unknown_tags = [tag for tag in normalized_tags if tag not in KNOWN_TAGS]\n if unknown_tags:\n errors.append(f\"Unknown tags (add to KNOWN_TAGS): {', '.join(sorted(unknown_tags))}\")\n except ValueError as e:\n errors.append(str(e))\n\n # Check content exists\n if not markdown_content.strip():\n errors.append(\"Rule content cannot be empty\")\n\n except Exception as e:\n errors.append(f\"Error reading file: {str(e)}\")\n\n return {\"errors\": errors, \"warnings\": warnings}\n\n\ndef main():\n \"\"\"Validate all rules in the sources directory.\"\"\"\n rules_dir = Path(sys.argv[1] if len(sys.argv) > 1 else \"sources\")\n\n if not rules_dir.exists():\n print(f\"❌ Directory {rules_dir} does not exist\")\n sys.exit(1)\n\n # Find all .md files recursively (excluding README and templates)\n md_files = [\n f for f in rules_dir.rglob(\"*.md\") \n if f.name.lower() != \"readme.md\" and not f.name.endswith(\".template\")\n ]\n\n if not md_files:\n print(f\"❌ No rule files found in {rules_dir}\")\n sys.exit(1)\n\n print(f\"🔍 Validating {len(md_files)} rules in {rules_dir} (recursive)\\n\")\n\n passed = 0\n failed = 0\n total_warnings = 0\n\n for md_file in sorted(md_files):\n result = validate_rule(md_file)\n errors = result[\"errors\"]\n warnings = result[\"warnings\"]\n\n if errors:\n failed += 1\n print(f\"❌ {md_file.name}\")\n for error in errors:\n print(f\" - {error}\")\n else:\n passed += 1\n if warnings:\n print(f\"✅ {md_file.name}\")\n for warning in warnings:\n print(f\" ⚠️ {warning}\")\n total_warnings += 1\n else:\n print(f\"✅ {md_file.name}\")\n\n # Summary\n print(f\"\\n📊 Results: {passed} passed, {failed} failed\")\n if total_warnings:\n print(f\" Warnings: {total_warnings}\")\n\n if failed > 0:\n print(\"\\n❌ Validation failed\")\n sys.exit(1)\n else:\n print(\"\\n✅ All rules valid!\")\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "src/validate_versions.py",
"content": "#!/usr/bin/env python3\n# Copyright 2025 Cisco Systems, Inc. and its affiliates\n#\n# SPDX-License-Identifier: Apache-2.0\n\n\"\"\"\nVersion Validation Script\n\nValidates that all version strings match across:\n- pyproject.toml\n- .claude-plugin/plugin.json\n- .claude-plugin/marketplace.json\n\"\"\"\n\nimport json\nimport re\nimport sys\nimport tomllib\nfrom pathlib import Path\nfrom typing import NamedTuple\n\n\nclass VersionCheck(NamedTuple):\n \"\"\"Result of a version check.\"\"\"\n\n file: str\n expected: str\n found: str\n matches: bool\n\n\ndef get_pyproject_version(root: Path) -> str:\n \"\"\"Get version from pyproject.toml.\"\"\"\n pyproject_path = root / \"pyproject.toml\"\n with open(pyproject_path, \"rb\") as f:\n data = tomllib.load(f)\n return data[\"project\"][\"version\"]\n\n\ndef get_plugin_version(root: Path) -> str:\n \"\"\"Get version from plugin.json.\"\"\"\n plugin_path = root / \".claude-plugin\" / \"plugin.json\"\n with open(plugin_path, encoding=\"utf-8\") as f:\n data = json.load(f)\n return data[\"version\"]\n\n\ndef set_plugin_version(version: str, root: Path) -> None:\n \"\"\"Set version in plugin.json.\"\"\"\n plugin_path = root / \".claude-plugin\" / \"plugin.json\"\n with open(plugin_path, encoding=\"utf-8\") as f:\n data = json.load(f)\n data[\"version\"] = version\n with open(plugin_path, \"w\", encoding=\"utf-8\") as f:\n json.dump(data, f, indent=2)\n f.write(\"\\n\")\n\n\ndef get_marketplace_version(root: Path) -> str:\n \"\"\"Get version from marketplace.json.\"\"\"\n marketplace_path = root / \".claude-plugin\" / \"marketplace.json\"\n with open(marketplace_path, encoding=\"utf-8\") as f:\n data = json.load(f)\n return data[\"plugins\"][0][\"version\"]\n\n\ndef set_marketplace_version(version: str, root: Path) -> None:\n \"\"\"Set version in marketplace.json.\"\"\"\n marketplace_path = root / \".claude-plugin\" / \"marketplace.json\"\n with open(marketplace_path, encoding=\"utf-8\") as f:\n data = json.load(f)\n for plugin in data.get(\"plugins\", []):\n plugin[\"version\"] = version\n with open(marketplace_path, \"w\", encoding=\"utf-8\") as f:\n json.dump(data, f, indent=2)\n f.write(\"\\n\")\n\n\ndef _read_front_matter_value(path: Path, key: str) -> str:\n \"\"\"Read a YAML front-matter value from a markdown file.\"\"\"\n content = path.read_text(encoding=\"utf-8\")\n front_matter_match = re.match(r\"^---\\s*\\n(.*?)\\n---\\s*\\n\", content, re.DOTALL)\n if not front_matter_match:\n raise ValueError(f\"Missing front matter in {path}\")\n front_matter = front_matter_match.group(1)\n value_match = re.search(\n rf'^{re.escape(key)}:\\s*\"([^\"]+)\"\\s*$',\n front_matter,\n re.MULTILINE,\n )\n if not value_match:\n raise ValueError(f\"Missing {key} in front matter for {path}\")\n return value_match.group(1)\n\n\ndef get_skill_codeguard_version(root: Path) -> str:\n \"\"\"Get codeguard-version from skills/software-security/SKILL.md.\"\"\"\n skill_path = root / \"skills\" / \"software-security\" / \"SKILL.md\"\n return _read_front_matter_value(skill_path, \"codeguard-version\")\n\n\ndef validate_versions(expected_version: str, root: Path = None) -> list[VersionCheck]:\n \"\"\"\n Validate all versions match the expected version.\n\n Args:\n expected_version: The version to validate against (e.g., from git tag)\n root: Project root directory (defaults to parent of this script)\n\n Returns:\n List of VersionCheck results\n \"\"\"\n if root is None:\n root = Path(__file__).parent.parent\n\n checks = [\n VersionCheck(\n \"pyproject.toml\", expected_version, get_pyproject_version(root), False\n ),\n VersionCheck(\"plugin.json\", expected_version, get_plugin_version(root), False),\n VersionCheck(\n \"marketplace.json\", expected_version, get_marketplace_version(root), False\n ),\n VersionCheck(\n \"SKILL.md\",\n expected_version,\n get_skill_codeguard_version(root),\n False,\n ),\n ]\n\n # Update matches field\n return [\n VersionCheck(c.file, c.expected, c.found, c.expected == c.found) for c in checks\n ]\n\n\ndef main() -> int:\n \"\"\"Main entry point for CLI.\"\"\"\n if len(sys.argv) != 2:\n print(\"Usage: validate_versions.py \")\n print(\"Example: validate_versions.py 1.0.0\")\n return 1\n\n expected_version = sys.argv[1]\n results = validate_versions(expected_version)\n\n # Print results\n all_match = True\n for check in results:\n if check.matches:\n print(f\"✅ {check.file}: {check.found}\")\n else:\n print(f\"❌ {check.file}: expected {check.expected}, found {check.found}\")\n all_match = False\n\n if all_match:\n print(f\"\\n✅ All versions match: {expected_version}\")\n return 0\n else:\n print(f\"\\n❌ Version mismatch detected!\")\n return 1\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n"
}
]