Skip to content

feat(stellar): detect unsafe operations in soroban contracts #557

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mijinummi merged 1 commit into from
Jun 26, 2026
+448 −215
Merged

feat(stellar): detect unsafe operations in soroban contracts #557

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
241 changes: 26 additions & 215 deletions PR_DESCRIPTION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,227 +1,38 @@
# 🚀 Major Feature Implementation: Rule Documentation, Pipeline Optimization, Audit Logging & Configurable Rules
## Summary

## Overview
This pull request introduces a new security rule to detect potentially unsafe operations in Soroban contracts. The rule flags a variety of patterns that can lead to security vulnerabilities and unexpected behavior, providing developers with actionable recommendations to improve the safety and reliability of their contracts.

This PR implements four major issues that significantly enhance the GasGuard ecosystem:
## What Changed

- **#209** 📘 Rule Documentation Generator
- **#210** 🔄 Rule Execution Pipeline Refactor
- **#211** 🧾 Audit Logging System
- **#212** ⚙️ Configurable Rule Engine
- Implemented a new security rule, `detect-unsafe-operations`, to identify unsafe patterns in Soroban contracts.
- The rule detects the following unsafe operations:
- `unsafe` blocks
- `unsafe fn`
- `.unwrap()` calls
- `panic!` macros
- `unreachable!` macros
- `std::mem::transmute`
- Raw pointer usage
- Unchecked arithmetic operators
- For each detected violation, the rule provides a detailed description of the issue and a recommendation for how to fix it.

## 📋 Changes Summary
## Why

### ✅ Issue #209 - Rule Documentation Generator
**Location**: `scripts/generate-rule-docs.ts`, `docs/rules/`
The use of unsafe operations in Soroban contracts can introduce serious security vulnerabilities, such as memory corruption, integer overflows, and unexpected panics. By detecting these patterns and providing clear guidance on how to avoid them, this new rule helps developers write more secure and robust contracts.

**Features**:
- Auto-scans TypeScript and Rust rule files for metadata extraction
- Generates organized markdown documentation by category (Solidity, Soroban, General)
- Creates searchable index with cross-references
- Supports examples, dependencies, and parameter documentation
- CLI-ready script for automated documentation generation
## Testing Performed

**Files Added**:
- `scripts/generate-rule-docs.ts` - Main documentation generator
- `docs/RULES.md` - Generated index
- `docs/rules/general.md` - General rules documentation
- `docs/rules/solidity.md` - Solidity rules documentation
- [x] Lint
- [x] Tests
- [x] Build

### ✅ Issue #210 - Rule Execution Pipeline Refactor
**Location**: `src/analysis/pipeline/pipeline-executor.ts`
## Edge Cases Considered

**Features**:
- **Parallel Execution**: Configurable concurrency for independent rules
- **Dependency-Aware Ordering**: Automatic level-based grouping
- **Performance Optimization**: Up to 4x faster execution for compatible rule sets
- **Backward Compatibility**: Sequential execution still available
- **Enhanced Metrics**: Execution time tracking and performance monitoring
- The rule correctly handles a variety of code formatting and style variations.
- The rule avoids false positives by ignoring non-arithmetic uses of `+`, `-`, and `*` operators.

**Key Improvements**:
```typescript
// New parallel execution with dependency resolution
const executor = new PipelineExecutor({
maxConcurrency: 4,
enableParallelExecution: true
});
```
## Risks

### ✅ Issue #211 - Audit Logging System
**Location**: `src/logger/`
None. The new rule is purely additive and does not introduce any breaking changes.

**Features**:
- **Centralized Logging**: Multi-provider architecture (console, file, audit)
- **Audit Trail**: Specialized logging for security and compliance
- **Real-time Events**: EventEmitter for live monitoring
- **Configurable Retention**: Automatic cleanup with configurable policies
- **Comprehensive Types**: Full TypeScript support with strict typing

**Core Components**:
- `LoggerService` - Main logging orchestration
- `AuditLogger` - Specialized audit event tracking
- `LoggerConfigManager` - Environment-based configuration

### ✅ Issue #212 - Configurable Rule Engine
**Location**: `src/config/`, `packages/config/`

**Features**:
- **Dynamic Rule Loading**: Enable/disable rules at runtime
- **JSON Configuration**: Human-readable config files with validation
- **Configuration Profiles**: Predefined rule sets for different use cases
- **Real-time Updates**: File watching for hot configuration reloads
- **Import/Export**: Backup and share configurations easily

**Configuration Example**:
```json
{
"rules": [
{
"id": "reentrancy-guard",
"enabled": true,
"severity": "critical",
"parameters": { "checkExternalCalls": true }
}
],
"profiles": [
{
"name": "strict-security",
"description": "High security profile"
}
]
}
```

## 🧪 Testing

- ✅ Rule documentation generator tested (found 2 rules, generated docs)
- ✅ Configuration system loads and validates properly
- ✅ All TypeScript compilation errors resolved
- ✅ Pipeline refactor maintains backward compatibility
- ✅ Audit logging system integrates with existing infrastructure

## 📁 File Structure

```
GasGuard/
├── scripts/
│ └── generate-rule-docs.ts # Documentation generator
├── docs/
│ ├── RULES.md # Generated rule index
│ └── rules/ # Rule documentation by category
├── src/
│ ├── logger/ # Audit logging system
│ │ ├── index.ts
│ │ ├── logger.service.ts
│ │ ├── audit-logger.ts
│ │ ├── logger.config.ts
│ │ └── logger.types.ts
│ ├── config/ # Configuration system
│ │ ├── index.ts
│ │ ├── config-manager.ts
│ │ ├── rule-config.ts
│ │ └── config.types.ts
│ └── analysis/pipeline/
│ └── pipeline-executor.ts # Enhanced with parallel execution
├── packages/config/
│ ├── index.ts
│ ├── rule-loader.ts
│ ├── config-validator.ts
│ └── config-schema.ts
└── config/
└── gasguard.config.json # Sample configuration
```

## 🚀 Usage Examples

### Generate Rule Documentation
```bash
npx ts-node scripts/generate-rule-docs.ts
```

### Configure Rules
```typescript
import { ConfigManager } from './src/config';

const config = ConfigManager.getInstance();
await config.enableRule('reentrancy-guard');
await config.updateRule('unused-state-variables', {
severity: 'high'
});
```

### Use Audit Logging
```typescript
import { AuditLogger } from './src/logger';

const audit = AuditLogger.getInstance();
await audit.logApiRequest({
userId: 'user123',
method: 'POST',
endpoint: '/api/analyze',
statusCode: 200
});
```

### Parallel Pipeline Execution
```typescript
const executor = new PipelineExecutor({
maxConcurrency: 8,
enableParallelExecution: true
});
```

## 🔧 Configuration

The system includes comprehensive configuration options:

- **Logging Levels**: debug, info, warn, error
- **Performance**: Concurrency limits, timeouts, parallel execution
- **Security**: API key validation, rate limiting
- **Features**: Auto-fix, detailed reporting, real-time monitoring

## 📊 Performance Improvements

- **Pipeline Execution**: Up to 4x faster for independent rules
- **Documentation Generation**: Automated, consistent, and searchable
- **Configuration Management**: Hot reload without service restart
- **Audit Logging**: Minimal performance impact with async processing

## 🔒 Security & Compliance

- **Audit Trail**: Complete traceability of all system actions
- **Immutable Logs**: Tamper-evident logging with integrity checks
- **Access Control**: Role-based configuration management
- **Data Protection**: Configurable retention and cleanup policies

## 🎯 Acceptance Criteria Met

- ✅ **#209**: Docs generated automatically with metadata extraction
- ✅ **#210**: Pipeline optimized with parallel execution and dependency-aware ordering
- ✅ **#211**: Logs stored and accessible with comprehensive audit trail
- ✅ **#212**: Rules configurable with dynamic loading and JSON-based management

## 📝 Breaking Changes

- **None** - All changes are backward compatible
- **Optional Features**: Parallel execution can be disabled
- **Configuration**: Default values provided for all new options

## 🔄 Migration Guide

1. **No immediate action required** - existing functionality preserved
2. **Optional**: Enable parallel execution for performance gains
3. **Optional**: Configure audit logging for compliance requirements
4. **Optional**: Use rule configuration for dynamic rule management

## 🧠 Future Enhancements

- Web UI for configuration management
- Advanced rule dependency visualization
- Real-time audit dashboard
- Automated rule performance profiling

---

**Total Changes**: 21 files, 3,546 insertions, 44 deletions
**Testing**: All implementations tested and verified
**Documentation**: Comprehensive docs and examples provided
Closes #496
Loading
Loading