# redstr - Cursor Rules
## ⚠️ CRITICAL FOR AI AGENTS: COMMIT MESSAGES AND PR TITLES
**ALL commits and PR titles MUST follow conventional commits format. This is enforced in CI.**
### Format (REQUIRED)
```
[TASK-ID] <type>(<scope>): <subject>
```
**OR (without task ID):**
```
<type>(<scope>): <subject>
```
### Valid Types (ONLY these are allowed)
- `feat` - New feature
- `fix` - Bug fix
- `docs` - Documentation
- `style` - Code style/formatting
- `refactor` - Code refactoring
- `test` - Tests
- `chore` - Maintenance
- `perf` - Performance
### Examples (CORRECT ✅)
- `[CF-001] feat(cloudflare): add Turnstile challenge variation`
- `fix(encoding): correct URL encoding for special characters`
- `docs(readme): update installation instructions`
- `test(builder): add TransformBuilder tests`
### Examples (INCORRECT ❌ - DO NOT USE)
- ❌ `Update code`
- ❌ `Fix bug`
- ❌ `Add feature`
- ❌ `Changes`
- ❌ `WIP`
- ❌ `Update README`
### Enforcement
- **CI will FAIL** if commits or PR titles don't follow this format
- **See "Commit Messages" section below for full details**
## Project Overview
redstr is a Rust library for string obfuscation and transformation designed for security testing (red team, blue team, purple team activities). The library provides 30+ transformation functions for WAF bypass, XSS evasion, SQL injection testing, phishing detection, and bot detection evasion.
## Core Principles
### 1. Zero Dependencies
- **CRITICAL**: The core library MUST use only Rust's standard library (`std`)
- Never add external dependencies to core functionality
- Optional features (like `serde`) should be behind feature flags
- When suggesting dependencies, always question if `std` can handle it
- Prefer implementing algorithms manually over adding crates
### 2. Security-Focused Design
- All functions should be designed with security testing use cases in mind
- Consider red team (offensive), blue team (defensive), and purple team (collaborative) perspectives
- Functions should help with:
- WAF bypass techniques
- XSS/SQL injection evasion
- Phishing domain generation
- Bot detection evasion
- Filter and detection validation
- Document security use cases in function doc comments
### 3. Performance Optimization
- Use efficient string operations (prefer `String::with_capacity` when size is known)
- Avoid unnecessary allocations
- Use iterators and functional patterns where appropriate
- Consider UTF-8 encoding implications for all string operations
- Profile performance-critical paths
### 4. Code Quality Standards
#### Rust Best Practices
- Use `edition = "2021"` Rust features
- Follow Rust naming conventions:
- Functions: `snake_case`
- Types: `PascalCase`
- Constants: `SCREAMING_SNAKE_CASE`
- Use `&str` for input parameters (borrowing)
- Return `String` for transformed output
- Prefer `&str` over `String` in function signatures when possible
- Use `Result` types for operations that can fail (though most transformations should not fail)
- Handle Unicode properly - use `char` iteration, not byte iteration for text transformations
#### Documentation
- Every public function MUST have:
- A doc comment with `///` describing what it does
- `# Examples` section with at least one usage example
- Security use case notes when relevant
- Include real-world examples in doc comments
- Document any non-obvious behavior or edge cases
- Reference related functions in doc comments
#### Testing
- Write unit tests for all public functions
- Test edge cases: empty strings, Unicode characters, special characters
- Test deterministic functions for exact output
- Test non-deterministic functions for expected properties (length, character preservation, etc.)
- Use `#[cfg(test)]` for test modules
- **MANDATORY**: Run `cargo test` before committing changes
- All tests must pass before committing
### 5. API Design
#### Function Signatures
- All transformation functions should follow: `fn function_name(input: &str) -> String`
- Functions should be pure (no side effects, deterministic when possible)
- For non-deterministic functions (random transformations), use internal RNG seeded from system time
- Keep functions focused on single responsibilities
#### Builder Pattern
- Use `TransformBuilder` for chaining multiple transformations
- Builder methods should consume `self` and return `Self` (owned)
- Builder should have a `.build()` method that returns the final `String`
- Add new builder methods when new transformations are added
#### Error Handling
- Most transformations should not fail (they operate on strings)
- If a transformation can fail, use `Result<String, Error>`
- Prefer panicking over silent failures for programming errors (e.g., invalid indices)
### 6. Project Structure
- Library code: `src/lib.rs`
- CLI binary: `src/main.rs` (only built with `cli` feature)
- Examples: `examples/` directory
- Tests: In `#[cfg(test)]` modules within source files
- Documentation: Comprehensive README.md with use cases
### 7. Feature Flags
- `default`: Core library only (no dependencies)
- `cli`: Enable CLI binary (`src/main.rs`)
- `serde`: Optional serde integration for serialization
- Always check feature flags when adding optional functionality
### 8. Publishing and Versioning
- Follow semantic versioning
- Update version in `Cargo.toml` before releases
- Publishing is automated via GitHub Actions on version tags (`v*`)
- Ensure all features work correctly before tagging releases
### 9. Code Style Guidelines
#### Formatting
- **MANDATORY**: Run `cargo fmt` before every commit
- Formatting is automatically checked in CI and will fail if not formatted
- Use 4 spaces for indentation
- Keep line length reasonable (aim for < 100 characters)
- Run `cargo fmt --check` to verify formatting without modifying files
#### Clippy
- **MANDATORY**: Run `cargo clippy -- -D warnings` before every commit
- All clippy warnings must be fixed or explicitly allowed with justification
- Prefer clippy suggestions for idiomatic Rust
- Suppress clippy warnings only when necessary with justification
- CI runs `cargo clippy -- -D warnings` and will fail on warnings
#### Commit Messages
- **MANDATORY**: All commits MUST follow conventional commits format
- **CRITICAL FOR AI AGENTS**: When making commits, ALWAYS use conventional commits format
- Format: `[TASK-ID] <type>(<scope>): <subject>`
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`
- Task ID is optional but recommended (e.g., `[CF-001]`)
- Examples:
- `[CF-001] feat(cloudflare): add Turnstile challenge variation`
- `fix(encoding): correct URL encoding for special characters`
- `docs(readme): update installation instructions`
- Commit messages are automatically validated using `cc-check` in CI
- **AI AGENTS MUST**: Before committing, verify the commit message follows the format above
- **AI AGENTS MUST**: Use the exact format - no variations, no exceptions
- See `CONTRIBUTING.md` for detailed commit message guidelines
#### Pull Request Titles (AI Agents)
- **MANDATORY**: PR titles MUST also follow conventional commits format
- Format: `[TASK-ID] <type>(<scope>): <subject>`
- PR titles are validated in CI and will fail if not in conventional commits format
- Examples:
- `[CF-001] feat(cloudflare): add Turnstile challenge variation`
- `fix(encoding): correct URL encoding for special characters`
- `docs(readme): update installation instructions`
- **AI AGENTS MUST**: When creating PRs, use conventional commits format for the title
#### Imports
- Group imports: std, external crates, local modules
- Use `use redstr::*;` in examples for simplicity
- Use explicit imports in library code for clarity
### 10. Security Considerations
- This library is for authorized security testing only
- Always include responsible use warnings in documentation
- Functions should not execute actual attacks, only generate test payloads
- Be mindful of homoglyph and typosquatting functions - document ethical use
### 11. When Adding New Functions
1. Check if it fits the security testing use case
2. Implement using only `std` library
3. Add comprehensive documentation with examples
4. Write unit tests covering edge cases
5. Add to `TransformBuilder` if it makes sense to chain
6. Update README.md with the new function
7. Add CLI support if applicable (in `src/main.rs`)
8. Consider adding to examples directory
### 12. Common Patterns
#### Random Number Generation
- Use internal `SimpleRng` struct for deterministic randomness
- Seed from system time: `SystemTime::now().duration_since(UNIX_EPOCH)`
- Use LCG (Linear Congruential Generator) for simple randomness needs
#### String Transformation Pattern
```rust
pub fn transformation(input: &str) -> String {
input
.chars()
.map(|c| {
// transformation logic
transformed_char
})
.collect()
}
```
#### Builder Pattern Pattern
```rust
pub fn transformation(mut self) -> Self {
self.text = transformation_function(&self.text);
self
}
```
## Examples of Good Code
### Good Function Design
```rust
/// Applies ROT13 cipher to the input.
///
/// ROT13 is a simple letter substitution cipher that replaces each letter
/// with the letter 13 positions after it in the alphabet.
///
/// # Examples
///
/// ```
/// use redstr::rot13;
/// assert_eq!(rot13("Hello"), "Uryyb");
/// assert_eq!(rot13("Uryyb"), "Hello"); // ROT13 is reversible
/// ```
pub fn rot13(input: &str) -> String {
input
.chars()
.map(|c| {
match c {
'a'..='z' => {
let offset = ((c as u8 - b'a' + 13) % 26) + b'a';
offset as char
}
'A'..='Z' => {
let offset = ((c as u8 - b'A' + 13) % 26) + b'A';
offset as char
}
_ => c,
}
})
.collect()
}
```
## What NOT to Do
1. ❌ Don't add external dependencies to core library
2. ❌ Don't use `unsafe` code unless absolutely necessary
3. ❌ Don't skip documentation for public functions
4. ❌ Don't write functions that mutate input (always return new String)
5. ❌ Don't ignore Unicode - always use `char` iteration, not byte iteration
6. ❌ Don't add features that don't relate to security testing
7. ❌ Don't commit code that doesn't pass `cargo test` and `cargo clippy -- -D warnings`
8. ❌ Don't break the zero-dependency principle
9. ❌ Don't commit without following conventional commits format - commits are validated in CI and will FAIL
10. ❌ Don't create PRs without conventional commits format in title - PR titles are validated in CI and will FAIL
11. ❌ Don't commit without running `cargo fmt` - formatting is enforced in CI
12. ❌ Don't commit without running `cargo check` - code must compile
13. ❌ **AI AGENTS: NEVER use generic commit messages like "Update code" or "Fix bug" - ALWAYS use conventional commits format**
## Workflow
1. Make changes to code
2. **ALWAYS run `cargo fmt` before committing** - Formatting is enforced in CI
3. **ALWAYS run `cargo check` before committing** - Ensures code compiles
4. Run `cargo clippy -- -D warnings` to check for issues
5. Run `cargo test` to ensure all tests pass
6. Update documentation if needed
7. Check that examples still work: `cargo run --example basic_usage`
8. Verify no new dependencies were added (check `Cargo.toml`)
9. **Write commit message following conventional commits format** (see Commit Messages section above)
10. **AI AGENTS: Before committing, double-check the commit message matches: `[TASK-ID] <type>(<scope>): <subject>`**
11. Commit messages are validated in CI - ensure format is correct before pushing
12. **AI AGENTS: When creating PRs, use conventional commits format for PR title as well**
**Pre-commit Checklist:**
- ✅ `cargo fmt` - Code is formatted (automatically checked by pre-commit hook)
- ✅ `cargo check` - Code compiles (automatically checked by pre-commit hook)
- ✅ `cargo clippy -- -D warnings` - No clippy warnings (automatically checked by pre-commit hook)
- ✅ `cargo test` - All tests pass (automatically checked by pre-commit hook)
- ✅ Commit message follows conventional commits format (validated in CI)
**Note:** A pre-commit hook automatically runs all the above checks (except commit message format) before each commit. All checks must pass before committing. Use `git commit --no-verify` only for WIP commits, never for final commits.
## Integration Examples
When suggesting code for integration with tools like Caido, Burp Suite, or EvilJinx, focus on:
- Simple, clean API usage
- Performance considerations for high-throughput scenarios
- Real-world security testing patterns
- Chain transformations using `TransformBuilder` for complex payloads