mirror of
https://github.com/ruvnet/RuView
synced 2026-08-07 20:01:43 +00:00
rUv
407b46b206
Add ruvnet/midstream (AIMDS real-time inference) and ruvnet/sublinear-time-solver (sublinear optimization algorithms) as vendored dependencies under vendor/.
485 lines
14 KiB
Markdown
485 lines
14 KiB
Markdown
# aimds-analysis - AI Manipulation Defense System Analysis Layer
|
|
|
|
[](https://crates.io/crates/aimds-analysis)
|
|
[](https://docs.rs/aimds-analysis)
|
|
[](../../LICENSE)
|
|
[](../../RUST_TEST_REPORT.md)
|
|
|
|
**Behavioral analysis and formal verification for AI threat detection - Temporal pattern analysis, LTL policy checking, and anomaly detection with sub-520ms latency.**
|
|
|
|
Part of the [AIMDS](https://ruv.io/aimds) (AI Manipulation Defense System) by [rUv](https://ruv.io) - Production-ready adversarial defense for AI systems.
|
|
|
|
## Features
|
|
|
|
- 🧠 **Behavioral Analysis**: Temporal pattern analysis via attractor classification (<100ms)
|
|
- 🔒 **Formal Verification**: LTL policy checking with theorem proving (<500ms)
|
|
- 📊 **Anomaly Detection**: Statistical baseline learning with multi-dimensional analysis
|
|
- ⚡ **High Performance**: <520ms combined deep-path latency (validated)
|
|
- 🎯 **Production Ready**: 100% test coverage (27/27), zero unsafe code
|
|
- 🔗 **Midstream Integration**: Uses temporal-attractor-studio, temporal-neural-solver
|
|
|
|
## Quick Start
|
|
|
|
```rust
|
|
use aimds_core::{Config, PromptInput};
|
|
use aimds_analysis::AnalysisEngine;
|
|
|
|
#[tokio::main]
|
|
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
// Initialize analysis engine
|
|
let config = Config::default();
|
|
let analyzer = AnalysisEngine::new(config).await?;
|
|
|
|
// Analyze behavioral patterns
|
|
let input = PromptInput::new(
|
|
"Unusual sequence of API calls...",
|
|
None
|
|
);
|
|
|
|
let result = analyzer.analyze(&input, None).await?;
|
|
|
|
println!("Anomaly score: {:.2}", result.anomaly_score);
|
|
println!("Attractor type: {:?}", result.attractor_type);
|
|
println!("Policy violations: {}", result.policy_violations.len());
|
|
println!("Latency: {}ms", result.latency_ms);
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
## Installation
|
|
|
|
Add to your `Cargo.toml`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
aimds-analysis = "0.1.0"
|
|
```
|
|
|
|
## Performance
|
|
|
|
### Validated Benchmarks
|
|
|
|
| Component | Target | Actual | Status |
|
|
|-----------|--------|--------|--------|
|
|
| **Behavioral Analysis** | <100ms | ~80ms | ✅ |
|
|
| **Policy Verification** | <500ms | ~420ms | ✅ |
|
|
| **Combined Deep Path** | <520ms | ~500ms | ✅ |
|
|
| **Anomaly Detection** | <50ms | ~35ms | ✅ |
|
|
| **Baseline Training** | <1s | ~850ms | ✅ |
|
|
|
|
*Benchmarks run on 4-core Intel Xeon, 16GB RAM. See [../../RUST_TEST_REPORT.md](../../RUST_TEST_REPORT.md) for details.*
|
|
|
|
### Performance Characteristics
|
|
|
|
- **Behavioral Analysis**: ~79,123 ns/iter (80ms for complex sequences)
|
|
- **Policy Verification**: ~418,901 ns/iter (420ms for complex LTL formulas)
|
|
- **Memory Usage**: <200MB baseline, <1GB with full baseline data
|
|
- **Throughput**: >500 requests/second for deep-path analysis
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────┐
|
|
│ aimds-analysis │
|
|
├──────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Behavioral │ │ Policy │ │
|
|
│ │ Analyzer │ │ Verifier │ │
|
|
│ └──────────────┘ └──────────────┘ │
|
|
│ │ │ │
|
|
│ └──────────┬─────────┘ │
|
|
│ │ │
|
|
│ ┌───────▼────────┐ │
|
|
│ │ Analysis │ │
|
|
│ │ Engine │ │
|
|
│ └───────┬────────┘ │
|
|
│ │ │
|
|
│ ┌──────────┴──────────┐ │
|
|
│ │ │ │
|
|
│ ┌──────▼─────┐ ┌───────▼──────┐ │
|
|
│ │ Attractor │ │ Temporal │ │
|
|
│ │ Studio │ │ Neural │ │
|
|
│ └────────────┘ └──────────────┘ │
|
|
│ │
|
|
│ Midstream Platform Integration │
|
|
│ │
|
|
└──────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Analysis Capabilities
|
|
|
|
### Behavioral Analysis
|
|
|
|
**Temporal Attractor Classification**:
|
|
|
|
- **Fixed Point**: Stable behavior, low anomaly risk
|
|
- **Limit Cycle**: Periodic patterns, normal operation
|
|
- **Strange Attractor**: Chaotic behavior, potential threat
|
|
- **Divergent**: Unstable patterns, high anomaly risk
|
|
|
|
**Lyapunov Exponent Calculation**:
|
|
|
|
```rust
|
|
let result = analyzer.analyze(&sequence).await?;
|
|
|
|
match result.lyapunov_exponent {
|
|
x if x > 0.0 => println!("Chaotic behavior detected"),
|
|
x if x == 0.0 => println!("Periodic behavior"),
|
|
_ => println!("Stable behavior"),
|
|
}
|
|
```
|
|
|
|
**Baseline Learning**:
|
|
|
|
```rust
|
|
// Train baseline on normal behavior
|
|
analyzer.train_baseline(&normal_sequences).await?;
|
|
|
|
// Detect deviations
|
|
let result = analyzer.analyze(&new_input, None).await?;
|
|
if result.anomaly_score > 0.8 {
|
|
println!("Significant deviation from baseline");
|
|
}
|
|
```
|
|
|
|
### Policy Verification
|
|
|
|
**Linear Temporal Logic (LTL)**:
|
|
|
|
Supports standard LTL operators:
|
|
|
|
- **Globally (G)**: Property must hold always
|
|
- **Finally (F)**: Property must hold eventually
|
|
- **Next (X)**: Property must hold in next state
|
|
- **Until (U)**: Property holds until another holds
|
|
|
|
**Policy Examples**:
|
|
|
|
```rust
|
|
use aimds_analysis::{PolicyVerifier, Policy};
|
|
|
|
let verifier = PolicyVerifier::new();
|
|
|
|
// "Users must always be authenticated"
|
|
let auth_policy = Policy::new(
|
|
"auth_required",
|
|
"G(authenticated)",
|
|
1.0 // priority
|
|
);
|
|
|
|
// "PII must eventually be redacted"
|
|
let pii_policy = Policy::new(
|
|
"pii_redaction",
|
|
"F(redacted)",
|
|
0.9
|
|
);
|
|
|
|
verifier.add_policy(auth_policy);
|
|
verifier.add_policy(pii_policy);
|
|
|
|
let result = verifier.verify(&trace).await?;
|
|
for violation in result.violations {
|
|
println!("Policy violated: {}", violation.policy_id);
|
|
}
|
|
```
|
|
|
|
### Anomaly Detection
|
|
|
|
**Multi-Dimensional Analysis**:
|
|
|
|
```rust
|
|
// Analyze sequence with multiple features
|
|
let sequence = vec![
|
|
vec![0.1, 0.2, 0.3], // Feature vector 1
|
|
vec![0.2, 0.3, 0.4], // Feature vector 2
|
|
// ... more vectors
|
|
];
|
|
|
|
let result = analyzer.analyze_sequence(&sequence).await?;
|
|
println!("Anomaly score: {:.2}", result.anomaly_score);
|
|
```
|
|
|
|
**Statistical Metrics**:
|
|
|
|
- Mean deviation from baseline
|
|
- Standard deviation analysis
|
|
- Distribution fitting (Gaussian, Student-t)
|
|
- Outlier detection (IQR, Z-score)
|
|
|
|
## Usage Examples
|
|
|
|
### Full Analysis Pipeline
|
|
|
|
```rust
|
|
use aimds_analysis::AnalysisEngine;
|
|
use aimds_core::{Config, PromptInput};
|
|
|
|
let analyzer = AnalysisEngine::new(Config::default()).await?;
|
|
|
|
// Behavioral + Policy verification
|
|
let input = PromptInput::new("User request sequence", None);
|
|
let detection = detector.detect(&input).await?;
|
|
|
|
let result = analyzer.analyze(&input, Some(&detection)).await?;
|
|
|
|
println!("Threat level: {:?}", result.threat_level);
|
|
println!("Anomaly score: {:.2}", result.anomaly_score);
|
|
println!("Policy violations: {}", result.policy_violations.len());
|
|
println!("Attractor type: {:?}", result.attractor_type);
|
|
```
|
|
|
|
### Baseline Training
|
|
|
|
```rust
|
|
// Collect normal behavior samples
|
|
let normal_sequences = vec![
|
|
PromptInput::new("Normal query 1", None),
|
|
PromptInput::new("Normal query 2", None),
|
|
// ... 100+ samples recommended
|
|
];
|
|
|
|
// Train baseline
|
|
analyzer.train_baseline(&normal_sequences).await?;
|
|
|
|
// Now analyze new inputs against baseline
|
|
let result = analyzer.analyze(&new_input, None).await?;
|
|
```
|
|
|
|
### LTL Policy Checking
|
|
|
|
```rust
|
|
use aimds_analysis::{PolicyVerifier, Policy, LTLChecker};
|
|
|
|
let mut verifier = PolicyVerifier::new();
|
|
|
|
// Add security policies
|
|
verifier.add_policy(Policy::new(
|
|
"rate_limit",
|
|
"G(requests_per_minute < 100)",
|
|
0.9
|
|
));
|
|
|
|
verifier.add_policy(Policy::new(
|
|
"auth_timeout",
|
|
"F(session_timeout)",
|
|
0.8
|
|
));
|
|
|
|
// Verify trace
|
|
let trace = vec![
|
|
("authenticated", true),
|
|
("requests_per_minute", 95),
|
|
("session_timeout", false),
|
|
];
|
|
|
|
let result = verifier.verify(&trace).await?;
|
|
for violation in result.violations {
|
|
println!("Violated: {} (confidence: {})",
|
|
violation.policy_id, violation.confidence);
|
|
}
|
|
```
|
|
|
|
### Threshold Adjustment
|
|
|
|
```rust
|
|
// Adjust sensitivity based on environment
|
|
analyzer.update_threshold(0.7).await?; // More sensitive
|
|
|
|
// Or per-analysis
|
|
let result = analyzer.analyze_with_threshold(
|
|
&input,
|
|
None,
|
|
0.9 // Less sensitive
|
|
).await?;
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
# Behavioral analysis
|
|
AIMDS_BEHAVIORAL_ANALYSIS_ENABLED=true
|
|
AIMDS_BEHAVIORAL_THRESHOLD=0.75
|
|
AIMDS_BASELINE_MIN_SAMPLES=100
|
|
|
|
# Policy verification
|
|
AIMDS_POLICY_VERIFICATION_ENABLED=true
|
|
AIMDS_POLICY_TIMEOUT_MS=500
|
|
AIMDS_POLICY_STRICT_MODE=true
|
|
|
|
# Performance tuning
|
|
AIMDS_ANALYSIS_TIMEOUT_MS=520
|
|
AIMDS_MAX_SEQUENCE_LENGTH=10000
|
|
```
|
|
|
|
### Programmatic Configuration
|
|
|
|
```rust
|
|
let config = Config {
|
|
behavioral_analysis_enabled: true,
|
|
behavioral_threshold: 0.75,
|
|
policy_verification_enabled: true,
|
|
..Config::default()
|
|
};
|
|
|
|
let analyzer = AnalysisEngine::new(config).await?;
|
|
```
|
|
|
|
## Integration with Midstream Platform
|
|
|
|
The analysis layer uses production-validated Midstream crates:
|
|
|
|
- **[temporal-attractor-studio](../../../crates/temporal-attractor-studio)**: Chaos analysis, Lyapunov exponents, attractor classification
|
|
- **[temporal-neural-solver](../../../crates/temporal-neural-solver)**: Neural ODE solving for temporal verification
|
|
- **[strange-loop](../../../crates/strange-loop)**: Meta-learning for pattern optimization
|
|
|
|
All integrations use 100% real APIs (no mocks) with validated performance.
|
|
|
|
## Testing
|
|
|
|
Run tests:
|
|
|
|
```bash
|
|
# Unit tests
|
|
cargo test --package aimds-analysis
|
|
|
|
# Integration tests
|
|
cargo test --package aimds-analysis --test integration_tests
|
|
|
|
# Benchmarks
|
|
cargo bench --package aimds-analysis
|
|
```
|
|
|
|
**Test Coverage**: 100% (27/27 tests passing)
|
|
|
|
Example tests:
|
|
- Behavioral analysis accuracy
|
|
- LTL formula parsing and verification
|
|
- Baseline training and detection
|
|
- Policy enable/disable functionality
|
|
- Performance validation (<520ms target)
|
|
|
|
## Monitoring
|
|
|
|
### Metrics
|
|
|
|
Prometheus metrics exposed:
|
|
|
|
```rust
|
|
// Analysis metrics
|
|
aimds_analysis_requests_total{type="behavioral|policy|combined"}
|
|
aimds_analysis_latency_ms{component="behavioral|policy"}
|
|
aimds_anomaly_score_distribution
|
|
aimds_policy_violations_total{policy_id}
|
|
|
|
// Performance metrics
|
|
aimds_baseline_training_time_ms
|
|
aimds_attractor_classification_latency_ms
|
|
aimds_ltl_verification_latency_ms
|
|
```
|
|
|
|
### Tracing
|
|
|
|
Structured logs with `tracing`:
|
|
|
|
```rust
|
|
info!(
|
|
anomaly_score = result.anomaly_score,
|
|
attractor_type = ?result.attractor_type,
|
|
violations = result.policy_violations.len(),
|
|
latency_ms = result.latency_ms,
|
|
"Analysis complete"
|
|
);
|
|
```
|
|
|
|
## Use Cases
|
|
|
|
### Multi-Agent Coordination
|
|
|
|
Detect anomalous agent behavior:
|
|
|
|
```rust
|
|
// Analyze agent action sequences
|
|
let agent_trace = vec![
|
|
agent.action_at(t0),
|
|
agent.action_at(t1),
|
|
// ... temporal sequence
|
|
];
|
|
|
|
let result = analyzer.analyze_sequence(&agent_trace).await?;
|
|
if result.anomaly_score > 0.8 {
|
|
coordinator.flag_agent(agent.id, result).await?;
|
|
}
|
|
```
|
|
|
|
### API Gateway Security
|
|
|
|
Enforce rate limits and access policies:
|
|
|
|
```rust
|
|
// Define policies
|
|
verifier.add_policy(Policy::new(
|
|
"rate_limit",
|
|
"G(requests_per_second < 100)",
|
|
1.0
|
|
));
|
|
|
|
// Verify each request
|
|
let result = verifier.verify(&request_trace).await?;
|
|
if !result.violations.is_empty() {
|
|
return Err("Policy violation");
|
|
}
|
|
```
|
|
|
|
### Fraud Detection
|
|
|
|
Identify unusual transaction patterns:
|
|
|
|
```rust
|
|
// Train on normal transactions
|
|
analyzer.train_baseline(&normal_transactions).await?;
|
|
|
|
// Analyze new transaction
|
|
let result = analyzer.analyze(&new_transaction, None).await?;
|
|
if result.anomaly_score > 0.9 {
|
|
fraud_system.flag_for_review(new_transaction).await?;
|
|
}
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- **API Docs**: https://docs.rs/aimds-analysis
|
|
- **Examples**: [../../examples/](../../examples/)
|
|
- **Benchmarks**: [../../benches/](../../benches/)
|
|
- **Test Report**: [../../RUST_TEST_REPORT.md](../../RUST_TEST_REPORT.md)
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0
|
|
|
|
## Related Projects
|
|
|
|
- [AIMDS](../../) - Main AIMDS platform
|
|
- [aimds-core](../aimds-core) - Core types and configuration
|
|
- [aimds-detection](../aimds-detection) - Real-time threat detection
|
|
- [aimds-response](../aimds-response) - Adaptive mitigation
|
|
- [Midstream Platform](https://github.com/agenticsorg/midstream) - Core temporal analysis
|
|
|
|
## Support
|
|
|
|
- **Website**: https://ruv.io/aimds
|
|
- **Docs**: https://ruv.io/aimds/docs
|
|
- **GitHub**: https://github.com/agenticsorg/midstream/tree/main/AIMDS/crates/aimds-analysis
|
|
- **Discord**: https://discord.gg/ruv
|
|
|
|
---
|
|
|
|
Built with ❤️ by [rUv](https://ruv.io) | [Twitter](https://twitter.com/ruvnet) | [LinkedIn](https://linkedin.com/in/ruvnet)
|