# OSVM DeepLogic AI Analysis Documentation
## Overview
OSVM DeepLogic is an advanced AI-powered security analysis system that goes beyond traditional vulnerability scanning. It provides intelligent analysis of complex logical vulnerabilities in Solana programs, offering specific code snippets of problematic areas and AI-generated remediation suggestions.
## What is DeepLogic Analysis?
DeepLogic analysis uses advanced AI techniques to identify sophisticated vulnerabilities that traditional static analysis tools often miss. Instead of just flagging potential issues, DeepLogic:
1. **Understands Context**: Analyzes the business logic and intended behavior of your code
2. **Identifies Logical Flaws**: Finds vulnerabilities in the program's logic flow and state management
3. **Provides Code Examples**: Shows exact problematic code segments with line numbers
4. **Suggests Fixes**: Generates corrected code examples with detailed explanations
5. **Explains Impact**: Describes potential attack scenarios and business impact
## Analysis Vectors
DeepLogic analyzes your code across four specialized vectors:
### 1. State Transition Analysis
- **Purpose**: Identifies how state changes might be exploited
- **Focus Areas**: State management, transitions between program states, race conditions
- **Common Issues**: Improper state validation, missing state checks, state inconsistencies
### 2. Economic Exploit Simulation
- **Purpose**: Detects financial attack scenarios
- **Focus Areas**: Token economics, reward mechanisms, pricing algorithms
- **Common Issues**: Flash loan attacks, MEV vulnerabilities, unfair reward distribution
### 3. Access Control & Authorization
- **Purpose**: Finds permission bypass vulnerabilities
- **Focus Areas**: Account validation, signer checks, authority verification
- **Common Issues**: Missing signer validation, authority bypass, privilege escalation
### 4. Mathematical Integrity
- **Purpose**: Identifies calculation and overflow issues
- **Focus Areas**: Arithmetic operations, precision handling, overflow protection
- **Common Issues**: Integer overflow/underflow, precision loss, rounding errors
## How to Use DeepLogic Analysis
### Basic Usage
DeepLogic analysis is **enabled by default** in OSVM audits:
```bash
# AI analysis with DeepLogic enabled automatically
osvm audit opensvm/aeamcp
# Audit local project with DeepLogic
osvm audit ./my-solana-project
# Disable AI analysis if needed
osvm audit ./my-project --noai
```
### Custom API Configuration
```bash
# Use custom AI endpoint
osvm audit opensvm/aeamcp --api-url http://localhost:3000/api/getAnswer
# With additional options
osvm audit opensvm/aeamcp --format html --output ./audit-results
```
## Interpreting DeepLogic Results
### Report Structure
DeepLogic findings appear in a dedicated section of your audit report:
```
🧠 DeepLogic AI Analysis
══════════════════════════════════════
[+] Title: DeepLogic: [Specific Vulnerability Name]
- Confidence Score: 0.85 (85% confidence)
- Severity: High
- Category: DeepLogic - [Analysis Vector]
- Analysis Vector: [EconomicExploit|StateTransition|AccessControl|MathematicalIntegrity]
```
### Key Components
1. **Title**: Descriptive name of the logical vulnerability
2. **Confidence Score**: AI confidence level (0.0-1.0)
3. **Severity**: Impact level (Critical, High, Medium, Low)
4. **Category**: Classification of the vulnerability type
5. **Analysis Vector**: Which of the four analysis types detected it
### Detailed Analysis Sections
Each DeepLogic finding includes:
#### 🤖 AI-Powered Analysis
Detailed explanation of the vulnerability, including:
- How the vulnerability works
- Why it's problematic
- Conditions under which it can be exploited
#### ⚠️ Risk Scenario
Step-by-step attack scenario showing:
- How an attacker would exploit the vulnerability
- What the attacker could gain
- Impact on legitimate users
#### 🔴 Problematic Code
Exact code snippet showing the vulnerability:
- File path and line numbers
- Specific lines of problematic code
- Context around the vulnerable code
#### 🟢 Suggested Fix
AI-generated corrected code:
- Improved version of the problematic code
- Additional imports or dependencies if needed
- Best practices implementation
#### 💡 Explanation of Fix
Detailed explanation of the suggested fix:
- Why the fix addresses the vulnerability
- How the fix improves security
- Any trade-offs or considerations
#### 🔧 Additional Considerations
Supplementary security advice:
- Edge cases to consider
- Additional testing recommendations
- Performance implications
- Alternative approaches
## Example DeepLogic Finding
### Economic Exploit: Unfair Reward Capture
```
🧠 DeepLogic AI Analysis
══════════════════════════════════════
[+] Title: DeepLogic: Potential Unfair Reward Capture via Transactional Liquidity
- Confidence Score: 0.85
- Severity: High
- Category: DeepLogic - Economic Exploit
- Analysis Vector: EconomicExploit
🤖 AI-Powered Analysis:
The claim_rewards function calculates a user's reward share based on their
instantaneous contribution to pool_state.total_liquidity. There appears to be
no time-lock, vesting, or snapshot mechanism to ensure the liquidity was
provided for a minimum duration. This makes the system vulnerable to
flash-deposit/withdraw attacks within a single transaction.
⚠️ Risk Scenario:
An attacker with significant capital could execute an atomic transaction:
1) deposit massive liquidity, 2) call claim_rewards, 3) withdraw massive
liquidity. This exploits the instantaneous calculation, draining rewards
from genuine, long-term liquidity providers.
🔴 Problematic Code (src/lib.rs:150-153):
```rust
// This calculation is based on current liquidity, vulnerable to flash-deposit attacks.
let user_share = get_user_liquidity(user.key) / pool_state.total_liquidity;
let rewards_to_claim = pool_state.accumulated_rewards * user_share;
// ... further logic using rewards_to_claim ...
```
🟢 Suggested Fix (src/lib.rs:150-153):
```rust
// Implement a time-weighted average or snapshot system for reward calculation.
// This example uses a hypothetical get_time_weighted_user_liquidity function.
use solana_program::clock::Clock;
use solana_program::sysvar::Sysvar;
let clock = Clock::get()?;
let current_timestamp = clock.unix_timestamp;
// A more robust calculation considering time spent with liquidity
let user_share = get_time_weighted_user_liquidity(user.key, &pool_state, current_timestamp)
/ pool_state.total_time_weighted_liquidity;
let rewards_to_claim = pool_state.accumulated_rewards * user_share;
```
💡 Explanation of Fix:
The proposed fix introduces the concept of time-weighted liquidity. Instead of
using the current liquidity amount, the system would track how much liquidity a
user has provided over time. This requires modifying get_user_liquidity and
potentially adding new state fields to the Pool and User structs.
🔧 Additional Considerations:
- This fix is conceptual and requires careful implementation of state tracking
- Consider the gas costs and complexity of maintaining such state
- A simpler alternative might be a lock-up period for rewards
- Implement comprehensive unit tests for the new logic
```
## Understanding Confidence Scores
DeepLogic provides confidence scores to help you prioritize findings:
- **0.9-1.0**: Very High Confidence - Likely a real vulnerability requiring immediate attention
- **0.7-0.8**: High Confidence - Should be investigated and likely fixed
- **0.5-0.6**: Medium Confidence - Worth reviewing, may be false positive
- **0.3-0.4**: Low Confidence - Possible issue, needs manual verification
- **0.1-0.2**: Very Low Confidence - Likely false positive, may ignore safely
## Extending Fix Suggestion Logic
### For Developers
If you want to extend or customize DeepLogic's fix suggestions:
1. **Code Extractor Module** (`src/utils/code_extractor.rs`):
- Handles code snippet extraction
- Contains pattern-based fix generation
- Can be extended with custom patterns
2. **AI Prompts** (`src/utils/audit.rs`):
- Contains the prompts sent to the AI service
- Can be customized for domain-specific analysis
- Supports different analysis vectors
3. **Template System** (`templates/audit_report.html`):
- Controls how DeepLogic findings are displayed
- Can be customized for different output formats
- Supports custom styling and formatting
### Custom Analysis Patterns
You can add custom vulnerability patterns by extending the code extractor:
```rust
// Example: Add custom pattern for oracle price validation
impl CodeExtractor {
pub fn detect_oracle_vulnerabilities(&self, content: &str) -> Vec<CodeSnippet> {
// Custom detection logic
// Generate custom fix suggestions
}
}
```
### Custom AI Prompts
Customize the AI analysis by modifying the prompt templates:
```rust
// Example: Add domain-specific context to prompts
fn build_deeplogic_prompt(&self, vulnerability: &AuditFinding) -> String {
format!(
"Analyze this Solana program vulnerability with focus on {}...",
self.domain_context
)
}
```
## Best Practices
### When to Trust DeepLogic
- **High confidence findings**: Almost always worth investigating
- **Consistent patterns**: If multiple findings point to the same issue
- **Critical severity**: Always review regardless of confidence
- **Business logic issues**: DeepLogic excels at these complex scenarios
### When to Manual Review
- **Low confidence findings**: Use human judgment
- **Complex business logic**: Verify AI understands your specific use case
- **Performance implications**: Consider the trade-offs of suggested fixes
- **Regulatory requirements**: Ensure fixes meet compliance needs
### Iterative Improvement
1. **Start with high-confidence findings**: Focus on clear vulnerabilities first
2. **Test suggested fixes**: Always test in development environment
3. **Document decisions**: Keep track of which findings you acted on
4. **Re-run analysis**: After fixes, run another audit to verify improvements
## Integration with Development Workflow
### CI/CD Integration
```bash
# Add to your CI pipeline
osvm audit opensvm/myproject --format json --output ./audit-results
```
### Pre-commit Hooks
```bash
# Add to pre-commit configuration
- repo: local
hooks:
- id: osvm-audit
name: OSVM Security Audit
entry: osvm audit --noai --format json
language: system
```
### Automation
```bash
# Schedule regular audits
0 0 * * 1 osvm audit opensvm/myproject --format html --output ./weekly-audit
```
## Troubleshooting
### Common Issues
1. **AI service unavailable**: Use `--noai` flag to run without AI analysis
2. **Low confidence scores**: May indicate complex logic that needs manual review
3. **False positives**: Use confidence scores and manual verification
4. **Missing context**: Ensure your code has sufficient comments and documentation
### Getting Help
- Check the confidence score first
- Review the risk scenario to understand the concern
- Test the suggested fix in a development environment
- Consult with security experts for high-impact findings
## Limitations
- **AI-based analysis**: May occasionally produce false positives or miss edge cases
- **Context dependency**: Works best with well-documented, clear code
- **Domain-specific knowledge**: May not understand very specialized business logic
- **Performance impact**: AI analysis adds time to the audit process
## Future Enhancements
- **Custom training**: Train DeepLogic on your specific codebase patterns
- **Integration with IDEs**: Real-time analysis during development
- **Community patterns**: Shared vulnerability patterns across projects
- **Automated testing**: Generate test cases for detected vulnerabilities