# Security Guard System
The Security Guard system provides protection against dangerous commands and operations in Stata dofiles. It acts as a safety layer between LLM-generated code and actual execution.
## Overview
The Security Guard is **enabled by default** to prevent accidental execution of destructive operations. It validates all dofile code against a blacklist of dangerous commands and patterns before execution.
### Key Features
- **Blacklist-Based Validation**: Blocks known dangerous commands
- **Pattern Matching**: Detects potentially dangerous operations using regex
- **Line-by-Line Analysis**: Provides detailed risk reporting with line numbers
- **Configurable**: Can be disabled if needed (not recommended)
- **Zero False Positives for Safe Code**: Only flags genuinely dangerous operations
## Dangerous Commands
The Security Guard blocks the following dangerous commands:
### Shell Execution Commands
| Command | Description | Example |
|---------|-------------|---------|
| `!` | Unix-style shell escape | `! ls -la` |
| `!!` | Extended shell command | `!! vi file.do` |
| `shell` | Shell command execution | `shell dir` |
| `xshell` | Extended shell for Mac/Unix(GUI) | `xshell vi file.do` |
| `winexec` | Windows program execution | `winexec notepad.exe` |
| `unixcmd` | Unix command execution | `unixcmd ls` |
### File Operations
| Command | Description | Risk |
|---------|-------------|------|
| `erase` | File deletion | Data loss |
| `rm` | File deletion (alias) | Data loss |
| `rmdir` | Directory removal | Data loss |
| `copy` | File copy | Can overwrite files |
### Code Execution
| Command | Description | Risk |
|---------|-------------|------|
| `run` | Run another do-file | Untrusted code execution |
| `do` | Execute do-file | Untrusted code execution |
| `include` | Include another do-file | Untrusted code execution |
## Configuration
### Enable/Disable Security Guard
#### Option 1: Configuration File
Edit `~/.statamcp/config.toml`:
```toml
[SECURITY]
IS_GUARD = true # Default: true
```
#### Option 2: Environment Variable
```bash
# Enable (default)
export STATA_MCP__IS_GUARD=true
# Disable (not recommended)
export STATA_MCP__IS_GUARD=false
```
### Default Behavior
- **Default**: Enabled (`IS_GUARD = true`)
- **Recommended**: Keep enabled for production use
- **Development**: Can be disabled for testing (use with caution)
## Usage
### Basic Usage
The Security Guard is automatically applied when using the `stata_do` tool:
```python
# When IS_GUARD is enabled (default)
result = stata_mcp.stata_do(code="""
sysuse auto
regress price mpg weight
""")
# Safe code executes normally
```
### Security Validation Example
When dangerous code is detected:
```python
result = stata_mcp.stata_do(code="""
sysuse auto
! rm -rf / # Dangerous command
""")
# Error: Security validation failed
# ❌ Security validation failed. Found dangerous items:
# - Line 3: command '!'
```
### Programmatic Usage
If you're using Stata-MCP as a library:
```python
from stata_mcp.guard import GuardValidator
# Create validator
validator = GuardValidator()
# Validate code
code = """
sysuse auto
regress price mpg weight
"""
report = validator.validate(code)
if report.is_safe:
print("✅ Code is safe to execute")
else:
print(f"❌ Found {len(report.dangerous_items)} dangerous items:")
for item in report.dangerous_items:
print(f" {item}")
```
## Security Report
### SecurityReport Object
```python
@dataclass
class SecurityReport:
is_safe: bool # True if no dangerous items found
dangerous_items: List[RiskItem] # List of detected risks
```
### RiskItem Object
```python
@dataclass
class RiskItem:
type: str # "command" or "pattern"
content: str # The dangerous content
line: int # Line number (1-indexed)
```
### Example Output
```python
# Safe code
report = validator.validate("sysuse auto")
print(report)
# Output: ✅ Code passed security validation
# Dangerous code
report = validator.validate("! rm file.txt")
print(report)
# Output:
# ❌ Security validation failed. Found dangerous items:
# - Line 1: command '!'
```
## Dangerous Patterns
The Security Guard uses regex patterns to detect dangerous operations:
### Shell Command Patterns
```python
r"!\s*\w+" # Shell escape with command: ! ls
r"!!\s*\w+" # Extended shell: !! vi file.do
r"shell\s+\w+" # Shell command: shell dir
r"xshell\s+\w+" # Extended shell: xshell vi file.do
r"winexec\s+\S+" # Windows execution: winexec program.exe
r"unixcmd\s+\w+" # Unix command: unixcmd ls
```
### File Operation Patterns
```python
r"erase\s+.*" # File deletion: erase file.dta
r"rm\s+.*" # File deletion: rm file.dta
r"rmdir\s+.*" # Directory removal: rmdir mydir
r"copy\s+.*" # File copy: copy file1.dta file2.dta
```
### Code Execution Patterns
```python
r"run\s+.*" # Run do-file: run script.do
r"\bdo\s+.*" # Execute do-file: do script.do
r"include\s+.*" # Include do-file: include setup.do
```
## Validation Process
### Step-by-Step Validation
1. **Code Input**: Receive dofile code string
2. **Line Split**: Split code into lines for line number tracking
3. **Filtering**: Skip empty lines and comments (starting with `*`)
4. **Command Check**: Check each line against dangerous commands
5. **Pattern Check**: Check each line against dangerous patterns
6. **Report Generation**: Create SecurityReport with all findings
### Example Validation
```python
code = """
* This is a comment
sysuse auto
! rm dangerous.txt # Line 3
regress price mpg
"""
report = validator.validate(code)
# Report:
# ❌ Security validation failed. Found dangerous items:
# - Line 3: command '!'
```
## Best Practices
### 1. Keep Security Guard Enabled
```toml
[SECURITY]
IS_GUARD = true # Always keep enabled
```
### 2. Review Security Reports
Always review security validation reports:
```python
report = validator.validate(code)
if not report.is_safe:
# Log or notify about dangerous items
for item in report.dangerous_items:
logger.warning(f"Dangerous item found: {item}")
```
### 3. Use Whitelist for Allowed Operations
If you need to execute certain dangerous operations:
1. Review the code manually
2. Remove dangerous commands
3. Use safe alternatives
Example:
```stata
* Instead of: ! rm tempfile.dta
* Use: erase tempfile.dta (still blocked, but shows intent)
* Better approach: Use Stata's built-in safe operations
capture erase tempfile.dta
```
### 4. Educate Users
Document which commands are blocked and why:
```markdown
## Blocked Commands
The following commands are blocked for security reasons:
- Shell commands (!, shell, xshell, etc.)
- File deletion (erase, rm)
- External code execution (run, do, include)
Please use safe alternatives or contact administrator for assistance.
```
## Troubleshooting
### False Positives
If you believe a command is incorrectly flagged:
1. **Review the command**: Is it actually dangerous?
2. **Check for patterns**: Does it match a dangerous pattern?
3. **Consider alternatives**: Is there a safer way to accomplish the task?
### Disabling Security Guard
**⚠️ Warning**: Disabling the Security Guard is not recommended.
Only disable if:
- You're in a trusted environment
- All code is manually reviewed
- You understand the risks
```bash
# Temporary disable (current session only)
export STATA_MCP__IS_GUARD=false
stata-mcp
# Permanent disable (add to config)
# Edit ~/.statamcp/config.toml
[SECURITY]
IS_GUARD = false
```
### Customizing Blacklist
You can extend the blacklist by modifying the code:
```python
from stata_mcp.guard.blacklist import DANGEROUS_COMMANDS
# Add custom dangerous commands
DANGEROUS_COMMANDS.add("my_dangerous_command")
# Use custom validator
from stata_mcp.guard import GuardValidator
validator = GuardValidator()
validator.dangerous_commands.add("another_command")
```
## Security Considerations
### What the Guard Protects Against
✅ **Prevents**:
- Shell command execution
- File deletion operations
- Untrusted code execution
- System-level operations
❌ **Does Not Prevent**:
- Data modification within Stata
- Infinite loops
- Memory exhaustion
- Stata crashes
### Limitations
The Security Guard:
- Does not analyze data flow
- Does not track variable values
- Does not prevent resource exhaustion
- Is not a substitute for proper code review
### Defense in Depth
The Security Guard is one layer of protection. Combine with:
1. **Monitoring**: Enable RAM monitoring (see [Monitoring Documentation](monitoring.md))
2. **Sandboxing**: Use isolated environments for untrusted code
3. **Code Review**: Manually review generated code
4. **Backups**: Maintain regular backups of important data
## Integration with MCP Tools
### Automatic Integration
The Security Guard is automatically integrated with:
- `stata_do`: Execute Stata do-files (validated by default)
- `write_dofile`: Create do-files (not validated until execution)
- `append_dofile`: Append to do-files (not validated until execution)
### Validation Flow
```
User Request → MCP Tool → Security Guard → Validation
↓
Pass? → Execute
↓
Fail? → Return Error
```
## Extensibility
### Creating Custom Validators
You can create custom validators for specific use cases:
```python
from stata_mcp.guard import GuardValidator, RiskItem, SecurityReport
class CustomValidator(GuardValidator):
"""Custom validator with additional rules."""
def validate(self, code: str) -> SecurityReport:
# Get base validation results
report = super().validate(code)
# Add custom validation logic
if "custom_dangerous_thing" in code:
report.dangerous_items.append(
RiskItem(
type="custom",
content="custom_dangerous_thing",
line=code.find("custom_dangerous_thing")
)
)
report.is_safe = False
return report
```
### Combining Multiple Validators
```python
from stata_mcp.guard import GuardValidator
# Create multiple validators
basic_validator = GuardValidator()
custom_validator = CustomValidator()
# Validate with both
code = "some stata code"
report1 = basic_validator.validate(code)
report2 = custom_validator.validate(code)
# Combine results
if report1.is_safe and report2.is_safe:
print("✅ All validations passed")
```
## Examples
### Example 1: Safe Code Execution
```python
from stata_mcp.guard import GuardValidator
validator = GuardValidator()
safe_code = """
* Load sample data
sysuse auto
* Run regression
regress price mpg weight
* Display results
display "R-squared: " + string(e(r2))
"""
report = validator.validate(safe_code)
print(report)
# Output: ✅ Code passed security validation
```
### Example 2: Dangerous Code Detection
```python
dangerous_code = """
sysuse auto
* This will be blocked
! rm -rf /important/data
regress price mpg
"""
report = validator.validate(dangerous_code)
print(report)
# Output:
# ❌ Security validation failed. Found dangerous items:
# - Line 5: command '!'
```
### Example 3: Multiple Violations
```python
multiple_violations = """
sysuse auto
shell delete file.txt
run untrusted_script.do
"""
report = validator.validate(multiple_violations)
print(f"Found {len(report.dangerous_items)} violations:")
for item in report.dangerous_items:
print(f" {item}")
# Output:
# Found 2 violations:
# Line 3: command 'shell'
# Line 4: pattern 'run\s+.*'
```
## Summary
The Security Guard system provides essential protection for automated Stata execution:
- ✅ **Enabled by default** for safety
- ✅ **Blocks dangerous commands** (shell, file deletion, etc.)
- ✅ **Pattern-based detection** for comprehensive coverage
- ✅ **Detailed reporting** with line numbers
- ✅ **Configurable** for different use cases
- ✅ **Zero overhead** when disabled (not recommended)
For production use, always keep the Security Guard enabled and review validation reports regularly.
