# SARIF Rust Library
[](https://crates.io/crates/sarif_rust)
[](https://docs.rs/sarif_rust)
[](https://github.com/khalidelborai/sarif_rust/actions)
[](https://codecov.io/gh/khalidelborai/sarif_rust)
[](https://opensource.org/licenses/MIT)
A comprehensive Rust library for parsing, generating, and manipulating [SARIF](https://sarifweb.azurewebsites.net/) (Static Analysis Results Interchange Format) v2.1.0 files.
SARIF is a standard JSON format for the output of static analysis tools. This library provides complete support for the SARIF v2.1.0 specification with type-safe parsing, generation, validation, and manipulation capabilities.
## Features
- ✅ **Complete SARIF v2.1.0 Support**: Full specification compliance with all optional fields
- 🔒 **Type-Safe API**: Leverages Rust's type system for correctness and safety
- 🏗️ **Builder Pattern**: Ergonomic API for programmatic SARIF generation
- 🔍 **Advanced Querying**: Powerful filtering and search capabilities
- 🔄 **Merge & Diff**: Combine multiple SARIF files or compare them
- 📊 **Multiple Formats**: Export to CSV, HTML, GitHub Security Advisory format
- ⚡ **High Performance**: Streaming parser for large files with memory efficiency
- ✅ **Comprehensive Validation**: Multiple validation levels from minimal to pedantic
- 🔄 **Schema Evolution**: Automatic migration between SARIF versions
## Quick Start
Add this to your `Cargo.toml`:
```toml
[dependencies]
sarif_rust = "0.2.0"
```
### Basic Usage
```rust
use sarif_rust::{SarifLog, SarifLogBuilder, Level};
// Parse existing SARIF file
let sarif: SarifLog = sarif_rust::from_file("results.sarif")?;
// Access results
for run in &sarif.runs {
println!("Tool: {}", run.tool.driver.name);
if let Some(results) = &run.results {
for result in results {
println!(" Issue: {}",
result.message.text.as_deref().unwrap_or("no message"));
}
}
}
// Create new SARIF programmatically
let new_sarif = SarifLogBuilder::new()
.with_schema("https://json.schemastore.org/sarif-2.1.0.json")
.build();
// Save to file
sarif_rust::to_file(&new_sarif, "output.sarif")?;
```
## Advanced Usage
### Querying and Filtering
```rust
use sarif_rust::utils::{SarifIndex, QueryBuilder, Level};
let sarif = sarif_rust::from_file("results.sarif")?;
let index = SarifIndex::from_sarif_log(&sarif)?;
// Query by rule ID
let security_issues = index.get_results_for_rule("security/xss")?;
// Complex filtering with query builder
let query = QueryBuilder::new()
.with_rule_id_filter("security/*")
.with_minimum_level(Level::Warning)
.with_file_pattern("*.js")
.with_text_search("password")
.build();
let results = query.execute(&index)?;
println!("Found {} security issues", results.len());
```
### Merging Multiple SARIF Files
```rust
use sarif_rust::utils::{SarifMerger, MergeConfig};
let baseline = sarif_rust::from_file("baseline.sarif")?;
let current = sarif_rust::from_file("current.sarif")?;
// Configure merge behavior
let config = MergeConfig::default()
.with_deduplication(true) // Remove duplicate results
.with_consolidation(true) // Merge runs from same tool
.with_include_added(true)
.with_include_removed(true);
let merger = SarifMerger::new(config);
let merged = merger.merge(vec![baseline, current])?;
sarif_rust::to_file(&merged, "merged.sarif")?;
```
### Format Conversion
```rust
use sarif_rust::utils::{SarifConverter, ConversionConfig, OutputFormat};
let sarif = sarif_rust::from_file("results.sarif")?;
let config = ConversionConfig::default()
.with_include_full_paths(true)
.with_max_message_length(Some(100));
let converter = SarifConverter::new(config);
// Convert to CSV
let csv_output = converter.to_csv(&sarif)?;
std::fs::write("results.csv", csv_output)?;
// Convert to HTML report
let html_output = converter.to_html(&sarif)?;
std::fs::write("report.html", html_output)?;
```
## Documentation
- **[Specification Analysis](SARIF_SPEC_ANALYSIS.md)**: Deep dive into SARIF v2.1.0 specification
- **[Implementation Plan](IMPLEMENTATION_PLAN.md)**: Detailed technical implementation roadmap
- **[API Documentation](https://docs.rs/sarif_rust)**: Complete API reference (when published)
## SARIF Specification Compliance
This library implements the complete [SARIF v2.1.0 specification](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html) including:
### Core Objects
- **SarifLog**: Root container with version and runs
- **Run**: Analysis tool execution with results and metadata
- **Result**: Individual findings with locations and metadata
- **Location**: Physical and logical location information
- **Tool**: Tool and component information
- **Artifact**: File and content references
### Advanced Features
- **External Property Files**: Large-scale analysis support
- **Taxonomies**: Rule categorization and classification
- **Code Flows**: Multi-step analysis paths
- **Threading Flows**: Multi-threaded analysis support
- **Web Requests/Responses**: Web application analysis
- **Fixes**: Automated fix suggestions
## Performance Characteristics
| Parse | 1-10 MB | < 100ms |
| Validate | 1-10 MB | < 50ms |
| Serialize | 1-10 MB | < 50ms |
| Stream Parse | 100+ MB | < 500MB RAM |
## Development Roadmap
### Phase 1: Core Types (Week 1)
- [x] Define SARIF object model
- [x] Implement core enums and types
- [x] Basic JSON serialization support
### Phase 2: Validation (Week 2)
- [ ] Custom validation traits
- [ ] URI and cross-reference validation
- [ ] Comprehensive error types
### Phase 3: Builders (Week 3)
- [ ] Fluent builder interfaces
- [ ] Type-safe construction
- [ ] Ergonomic API design
### Phase 4: Advanced Features (Week 4)
- [ ] Streaming parser implementation
- [ ] Cross-reference indexing
- [ ] Memory optimization
### Phase 5: Polish (Week 5)
- [ ] Comprehensive testing
- [ ] Documentation and examples
- [ ] Performance benchmarking
## Contributing
Contributions are welcome! Please see our [contribution guidelines](CONTRIBUTING.md) for details on:
- Code style and formatting
- Testing requirements
- Documentation standards
- Pull request process
## License
This project is licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT License ([LICENSE-MIT](LICENSE-MIT))
at your option.
## Related Projects
- [SARIF Standard](https://sarifweb.azurewebsites.net/): Official SARIF specification and tools
- [Microsoft SARIF SDK](https://github.com/microsoft/sarif-sdk): .NET implementation
- [sarif-python](https://github.com/microsoft/sarif-python): Python SARIF library
---
**Status**: 🚧 Under Development - See [Implementation Plan](IMPLEMENTATION_PLAN.md) for current progress