d-bis/smom-dbis-138
4
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

Add Oracle Aggregator and CCIP Integration

Browse Source 
- Introduced Aggregator.sol for Chainlink-compatible oracle functionality, including round-based updates and access control.
- Added OracleWithCCIP.sol to extend Aggregator with CCIP cross-chain messaging capabilities.
- Created .gitmodules to include OpenZeppelin contracts as a submodule.
- Developed a comprehensive deployment guide in NEXT_STEPS_COMPLETE_GUIDE.md for Phase 2 and smart contract deployment.
- Implemented Vite configuration for the orchestration portal, supporting both Vue and React frameworks.
- Added server-side logic for the Multi-Cloud Orchestration Portal, including API endpoints for environment management and monitoring.
- Created scripts for resource import and usage validation across non-US regions.
- Added tests for CCIP error handling and integration to ensure robust functionality.
- Included various new files and directories for the orchestration portal and deployment scripts.
This commit is contained in:
defiQUG
2025-12-12 14:57:48 -08:00
parent a1466e4005
commit 1fb7266469
1720 changed files with 241279 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
docs/security/SECURITY.md Normal file
View File

@@ -0,0 +1,182 @@
# Security Documentation
## Security Overview
The DeFi Oracle Meta Mainnet implements multiple layers of security to protect the network and its users.
## Key Management
### Validator Keys
- Stored in Azure Key Vault
- Never stored on disk
- Rotated every 90 days
- Access restricted to validators only
### Oracle Keys
- Stored in Azure Key Vault
- Used via EthSigner
- Rotated every 90 days
- Access restricted to oracle publisher service
### Key Rotation
1. Generate new keys
2. Update Key Vault
3. Update node configurations
4. Restart nodes
5. Verify new keys are working
6. Remove old keys after verification
## Network Security
### Network Segmentation
- **Validators**: Private subnets, no public IPs
- **Sentries**: Public subnets, P2P access only
- **RPC Nodes**: DMZ subnet, HTTPS only
### Firewall Rules
- **Validators**: Internal communication only
- **Sentries**: P2P (30303) and internal communication
- **RPC Nodes**: HTTPS (443) and internal communication
### TLS/SSL
- TLS 1.2+ for all HTTPS connections
- mTLS for internal communication
- Certificate rotation every 90 days
## Access Control
### Node Permissioning
- Static node allowlists
- Prevents unauthorized nodes from joining
- Updated via configuration files
### Account Permissioning
- Account allowlists for RPC methods
- Prevents unauthorized transactions
- Updated via configuration files
### API Gateway
- Rate limiting per IP
- API key authentication (optional)
- Method allowlists
- CORS configuration
## Security Monitoring
### Logging
- All node operations logged
- Structured logging (JSON)
- Log aggregation (Loki)
- Log retention (30 days)
### Monitoring
- Prometheus metrics
- Alert rules for security events
- Grafana dashboards
- Alertmanager notifications
### Incident Response
- Security incident playbook
- Incident response team
- Escalation procedures
- Post-incident reviews
## Vulnerability Management
### Regular Audits
- Code audits quarterly
- Security audits annually
- Penetration testing annually
- Dependency updates monthly
### Patch Management
- Security patches applied within 24 hours
- Regular updates for dependencies
- Node software updates quarterly
- Emergency patches as needed
## Compliance
### Data Protection
- No personal data stored on-chain
- Privacy by design
- Data retention policies
- GDPR compliance (if applicable)
### Access Logging
- All RPC requests logged
- Access logs retained for 90 days
- Audit trails for admin operations
- Compliance reporting
## Security Best Practices
### For Operators
1. Use strong passwords
2. Enable multi-factor authentication
3. Rotate keys regularly
4. Monitor security alerts
5. Keep software updated
### For Developers
1. Follow secure coding practices
2. Use dependency scanning
3. Perform code reviews
4. Test security controls
5. Document security assumptions
### For Users
1. Verify contract addresses
2. Use trusted RPC endpoints
3. Check transaction details
4. Monitor account activity
5. Report suspicious activity
## Security Incidents
### Reporting
- Report security issues to security@d-bis.org
- Include detailed information
- Do not disclose publicly until fixed
### Response
1. Acknowledge receipt
2. Assess severity
3. Develop mitigation
4. Deploy fix
5. Notify users
6. Post-incident review
## Security Contacts
- **Security Team**: security@d-bis.org
- **Emergency**: +1-XXX-XXX-XXXX
- **PGP Key**: [Link to PGP key]
## Security Resources
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [Ethereum Security](https://ethereum.org/en/developers/docs/security/)
- [Besu Security](https://besu.hyperledger.org/en/stable/)

306
docs/security/SECURITY_AUDIT_CHECKLIST.md Normal file
View File

@@ -0,0 +1,306 @@
# Security Audit Checklist for Refactored Contracts
## Overview
This checklist provides security considerations for contracts refactored to remove OpenZeppelin dependencies.
## General Security Checklist
### Access Control
- [ ] **Admin Pattern**
- [ ] Admin address is set in constructor
- [ ] Admin address is validated (not zero address)
- [ ] Admin functions are protected with `onlyAdmin` modifier
- [ ] Admin can be changed with `changeAdmin` function
- [ ] New admin is validated (not zero address)
- [ ] Admin change is logged with event
- [ ] **Access Control Functions**
- [ ] All admin functions use `onlyAdmin` modifier
- [ ] No public functions with admin privileges
- [ ] No functions that bypass access control
- [ ] Access control is consistent across contract
### Token Operations
- [ ] **ERC20 Token Transfers**
- [ ] Token transfers use standard ERC20 calls
- [ ] Transfer return values are checked
- [ ] Transfer failures revert with clear error messages
- [ ] Token addresses are validated (not zero address)
- [ ] Token amounts are validated (greater than zero)
- [ ] **Token Approvals**
- [ ] Token approvals use standard ERC20 calls
- [ ] Approval return values are checked
- [ ] Approval failures revert with clear error messages
- [ ] Approval amounts are validated
- [ ] Approval spender is validated (not zero address)
- [ ] **Token Balance Checks**
- [ ] Balance checks are performed before transfers
- [ ] Balance checks use standard ERC20 calls
- [ ] Balance checks are accurate
- [ ] Balance checks handle edge cases
### Input Validation
- [ ] **Address Validation**
- [ ] All addresses are validated (not zero address)
- [ ] Address validation is consistent
- [ ] Address validation has clear error messages
- [ ] Address validation is performed early
- [ ] **Amount Validation**
- [ ] All amounts are validated (greater than zero)
- [ ] Amount validation is consistent
- [ ] Amount validation has clear error messages
- [ ] Amount validation handles overflow/underflow
- [ ] **Parameter Validation**
- [ ] All parameters are validated
- [ ] Parameter validation is consistent
- [ ] Parameter validation has clear error messages
- [ ] Parameter validation is performed early
### Error Handling
- [ ] **Error Messages**
- [ ] All error messages are clear and descriptive
- [ ] Error messages follow consistent format
- [ ] Error messages include contract name prefix
- [ ] Error messages are helpful for debugging
- [ ] **Revert Conditions**
- [ ] All revert conditions are explicit
- [ ] Revert conditions use `require` statements
- [ ] Revert conditions are checked early
- [ ] Revert conditions handle edge cases
### Reentrancy Protection
- [ ] **Reentrancy Guards**
- [ ] Reentrancy guards are used where needed
- [ ] Reentrancy guards are consistent
- [ ] Reentrancy guards are effective
- [ ] Reentrancy guards handle all entry points
- [ ] **External Calls**
- [ ] External calls are made after state changes
- [ ] External calls are validated
- [ ] External calls handle failures
- [ ] External calls don't allow reentrancy
### State Management
- [ ] **State Variables**
- [ ] State variables are properly initialized
- [ ] State variables are properly updated
- [ ] State variables are properly validated
- [ ] State variables are properly protected
- [ ] **State Changes**
- [ ] State changes are atomic
- [ ] State changes are consistent
- [ ] State changes are validated
- [ ] State changes are logged with events
### Events
- [ ] **Event Logging**
- [ ] All important events are logged
- [ ] Events include all relevant parameters
- [ ] Events are indexed where appropriate
- [ ] Events follow consistent naming
### Gas Optimization
- [ ] **Gas Efficiency**
- [ ] Contract is gas-efficient
- [ ] Unnecessary operations are avoided
- [ ] Storage operations are optimized
- [ ] External calls are minimized
### Code Quality
- [ ] **Code Structure**
- [ ] Code is well-structured
- [ ] Code is well-documented
- [ ] Code follows best practices
- [ ] Code is maintainable
- [ ] **Code Review**
- [ ] Code has been reviewed
- [ ] Code review comments have been addressed
- [ ] Code follows project standards
- [ ] Code is consistent with other contracts
---
## Contract-Specific Checklists
### CCIP Contracts (CCIPSender, CCIPRouter, CCIPRouterOptimized)
- [ ] **SafeERC20 Replacement**
- [ ] Standard ERC20 calls are used
- [ ] Transfer return values are checked
- [ ] Approval return values are checked
- [ ] Error messages are clear
- [ ] Only standard ERC20 tokens are used
- [ ] **Fee Token Handling**
- [ ] Fee token is validated
- [ ] Fee token transfers are safe
- [ ] Fee token approvals are safe
- [ ] Fee token balance is checked
- [ ] Fee token errors are handled
- [ ] **CCIP Integration**
- [ ] CCIP router is validated
- [ ] CCIP messages are validated
- [ ] CCIP fees are calculated correctly
- [ ] CCIP errors are handled
- [ ] CCIP replay protection is implemented
### Governance Contracts (MultiSig, Voting)
- [ ] **Ownable Replacement**
- [ ] Custom admin pattern is used
- [ ] Admin functions are protected
- [ ] Admin can be changed
- [ ] New admin is validated
- [ ] Admin change is logged
- [ ] **Access Control**
- [ ] Access control is consistent
- [ ] Access control is effective
- [ ] Access control handles edge cases
- [ ] Access control is well-tested
- [ ] **Governance Logic**
- [ ] Governance logic is correct
- [ ] Governance logic is secure
- [ ] Governance logic is well-tested
- [ ] Governance logic handles edge cases
---
## Testing Checklist
### Unit Tests
- [ ] **Test Coverage**
- [ ] All functions are tested
- [ ] All edge cases are tested
- [ ] All error cases are tested
- [ ] Test coverage is high
- [ ] **Test Quality**
- [ ] Tests are comprehensive
- [ ] Tests are well-written
- [ ] Tests are maintainable
- [ ] Tests follow best practices
### Integration Tests
- [ ] **Integration Testing**
- [ ] Contracts are tested together
- [ ] Integration tests are comprehensive
- [ ] Integration tests are well-written
- [ ] Integration tests are maintainable
### Security Tests
- [ ] **Security Testing**
- [ ] Security tests are performed
- [ ] Security vulnerabilities are tested
- [ ] Security tests are comprehensive
- [ ] Security tests are well-written
---
## Deployment Checklist
### Pre-Deployment
- [ ] **Code Review**
- [ ] Code has been reviewed
- [ ] Code review comments have been addressed
- [ ] Code follows project standards
- [ ] **Testing**
- [ ] All tests pass
- [ ] Test coverage is high
- [ ] Security tests are performed
- [ ] **Documentation**
- [ ] Documentation is complete
- [ ] Documentation is accurate
- [ ] Documentation is up-to-date
### Deployment
- [ ] **Deployment Scripts**
- [ ] Deployment scripts are tested
- [ ] Deployment scripts are secure
- [ ] Deployment scripts are well-documented
- [ ] **Deployment Verification**
- [ ] Contracts are deployed correctly
- [ ] Contract addresses are verified
- [ ] Contract functionality is verified
### Post-Deployment
- [ ] **Monitoring**
- [ ] Contracts are monitored
- [ ] Contract events are logged
- [ ] Contract performance is tracked
- [ ] **Maintenance**
- [ ] Contracts are maintained
- [ ] Contract updates are planned
- [ ] Contract security is reviewed
---
## References
### Contract Examples
- `contracts/ccip/CCIPWETH9Bridge.sol` - Custom implementation ✅
- `contracts/ccip/CCIPWETH10Bridge.sol` - Custom implementation ✅
- `contracts/tokens/WETH10.sol` - Custom implementation ✅
### Documentation
- [Migration Guide](./MIGRATION_GUIDE.md)
- [Contract Inventory](./CONTRACT_INVENTORY.md)
- [OpenZeppelin Usage Analysis](./OPENZEPPELIN_USAGE_ANALYSIS.md)
- [Dependencies Guide](./DEPENDENCIES.md)
---
## Summary
### Key Security Considerations
1. ✅ **Access Control**: Use custom admin pattern with proper validation
2. ✅ **Token Operations**: Use standard ERC20 calls with return value checks
3. ✅ **Input Validation**: Validate all inputs with clear error messages
4. ✅ **Error Handling**: Use explicit error messages with require statements
5. ✅ **Reentrancy Protection**: Protect against reentrancy attacks
6. ✅ **State Management**: Manage state changes safely and atomically
7. ✅ **Events**: Log all important events
8. ✅ **Gas Optimization**: Optimize gas usage where possible
9. ✅ **Code Quality**: Follow best practices and project standards
10. ✅ **Testing**: Comprehensive testing with high coverage
---
## Questions?
For questions about security audit checklists, refer to:
- [Migration Guide](./MIGRATION_GUIDE.md)
- [Contract Inventory](./CONTRACT_INVENTORY.md)
- [OpenZeppelin Usage Analysis](./OPENZEPPELIN_USAGE_ANALYSIS.md)

92
docs/security/SECURITY_COMPLIANCE.md Normal file
View File

@@ -0,0 +1,92 @@
# Security Compliance Documentation
## Overview
This document outlines security compliance requirements and controls for the DeFi Oracle Meta Mainnet.
## Security Controls
### Access Control
- **Key Management**: Azure Key Vault for validator keys
- **RBAC**: Role-based access control in Kubernetes
- **Network Policies**: Network isolation and segmentation
- **API Authentication**: API keys and JWT tokens
### Network Security
- **Private Subnets**: Validators in private subnets
- **NSGs**: Network Security Groups with restrictive rules
- **WAF**: Web Application Firewall for RPC endpoints
- **TLS**: TLS encryption for all external communication
### Application Security
- **Security Scanning**: SolidityScan, Slither, Mythril
- **Dependency Scanning**: Snyk, Trivy
- **Container Scanning**: Trivy for Docker images
- **Code Review**: All code changes reviewed
### Monitoring and Alerting
- **Security Monitoring**: Azure Security Center
- **Logging**: Centralized logging with Loki
- **Alerting**: Prometheus and Alertmanager
- **Incident Response**: Automated incident response
## Compliance Requirements
### Regulatory Compliance
- **Data Protection**: GDPR compliance for EU data
- **Financial Regulations**: Compliance with financial regulations
- **Audit Trails**: Complete audit trails for all operations
### Security Standards
- **OWASP**: OWASP Top 10 compliance
- **NIST**: NIST Cybersecurity Framework alignment
- **ISO 27001**: ISO 27001 security controls
## Security Audit Procedures
### Pre-Deployment Audits
1. **Code Review**: All code reviewed
2. **Security Scanning**: Automated security scans
3. **Penetration Testing**: Regular penetration tests
4. **Audit Reports**: Security audit reports
### Ongoing Audits
1. **Regular Scans**: Weekly security scans
2. **Dependency Updates**: Regular dependency updates
3. **Vulnerability Management**: Vulnerability tracking
4. **Incident Reviews**: Post-incident reviews
## Security Monitoring Tools
### Current Tools
- **SolidityScan**: Contract vulnerability scanning
- **Slither**: Static analysis
- **Mythril**: Dynamic analysis
- **Snyk**: Dependency scanning
- **Trivy**: Container scanning
- **Azure Security Center**: Infrastructure security
### Future Enhancements
- **Formal Verification**: Formal verification tools
- **Fuzzing**: Automated fuzzing
- **Penetration Testing**: Regular penetration tests
- **Security Monitoring**: Enhanced security monitoring
## Best Practices
1. **Security First**: Security-first approach
2. **Regular Updates**: Keep dependencies updated
3. **Monitoring**: Continuous security monitoring
4. **Documentation**: Document security decisions
5. **Training**: Security training for team

208
docs/security/SECURITY_SCANNING.md Normal file
View File

@@ -0,0 +1,208 @@
# Security Scanning Process
## Overview
This document describes the security scanning process for the DeFi Oracle Meta Mainnet project.
## Scanning Tools
### 1. SolidityScan
**Purpose**: Automated contract vulnerability scanning
**Usage**:
```bash
# Manual scan
solidityscan --api-key $API_KEY --project-path .
# CI/CD integration
# See .github/workflows/ci.yml
```
**Reports**: Available in SolidityScan dashboard and Blockscout UI
### 2. Slither
**Purpose**: Static analysis for Solidity contracts
**Usage**:
```bash
./scripts/security/slither-scan.sh
```
**Reports**: `reports/slither/slither-report.json` and `slither-report.txt`
### 3. Mythril
**Purpose**: Dynamic analysis for Solidity contracts
**Usage**:
```bash
./scripts/security/mythril-scan.sh
```
**Reports**: `reports/mythril/*.json` and `*.txt` files
### 4. Snyk
**Purpose**: Dependency scanning for Python and Node.js
**Usage**:
```bash
snyk test --severity-threshold=high
```
**Reports**: Available in Snyk dashboard
### 5. Trivy
**Purpose**: Container image vulnerability scanning
**Usage**:
```bash
trivy image <image-name>
```
**Reports**: SARIF format for GitHub integration
## Scanning Workflow
### Pre-Commit
1. Run `forge fmt --check` for formatting
2. Run `forge test` for unit tests
3. Run Slither for static analysis (optional)
### CI/CD Pipeline
The CI/CD pipeline automatically runs:
1. **Contract Compilation**: `forge build`
2. **Unit Tests**: `forge test`
3. **Slither**: Static analysis
4. **Mythril**: Dynamic analysis
5. **SolidityScan**: Automated scanning (if API key configured)
6. **Snyk**: Dependency scanning
7. **Trivy**: Container scanning
### Pre-Deployment
1. Run all security scans
2. Review all reports
3. Fix high-severity issues
4. Document security decisions
5. Get approval for deployment
## Report Review Process
### 1. High Severity Issues
**Action**: Fix immediately before deployment
**Process**:
1. Review issue details
2. Assess impact
3. Implement fix
4. Re-scan to verify
5. Document fix
### 2. Medium Severity Issues
**Action**: Fix before next release
**Process**:
1. Review issue details
2. Plan fix
3. Schedule for next sprint
4. Track in issue tracker
### 3. Low Severity Issues
**Action**: Fix as time permits
**Process**:
1. Review issue details
2. Assess priority
3. Add to backlog
4. Fix during maintenance
## Security Score Interpretation
### SolidityScan Scores
- **90-100**: Excellent - Production ready
- **70-89**: Good - Minor improvements recommended
- **50-69**: Fair - Should address issues before production
- **0-49**: Poor - Must fix before production
### Slither/Mythril
- **High**: Critical issues - Fix immediately
- **Medium**: Important issues - Fix before release
- **Low**: Minor issues - Fix as time permits
- **Informational**: Best practices - Consider fixing
## Continuous Monitoring
### Automated Scanning
- **On Commit**: CI/CD runs all scans
- **On PR**: Full scan suite
- **Daily**: Scheduled scans for dependencies
- **Weekly**: Comprehensive security audit
### Alerting
Set up alerts for:
- High-severity vulnerabilities
- New vulnerabilities in dependencies
- Security score drops
- Scan failures
## Remediation Process
### 1. Identify Issue
- Review scan reports
- Understand vulnerability
- Assess impact
### 2. Plan Fix
- Research solution
- Design fix
- Test approach
### 3. Implement Fix
- Write code
- Add tests
- Update documentation
### 4. Verify Fix
- Re-run scans
- Verify issue resolved
- Check no regressions
### 5. Deploy
- Deploy fix
- Monitor for issues
- Document resolution
## Best Practices
1. **Scan Early**: Run scans during development
2. **Fix Quickly**: Address issues as soon as found
3. **Document**: Document security decisions
4. **Review**: Regular security reviews
5. **Update**: Keep scanning tools updated
6. **Train**: Train team on security best practices
## References
- [SolidityScan Setup](docs/SOLIDITYSCAN_SETUP.md)
- [Security Scanning Guide](docs/SECURITY_SCANNING_GUIDE.md)
- [Security Scores](docs/SECURITY_SCORES.md)

242
docs/security/SECURITY_SCANNING_GUIDE.md Normal file
View File

@@ -0,0 +1,242 @@
# Security Scanning Guide
**Last Updated**: 2025-01-27
**Status**: Active
This guide explains how to use the security scanning tools integrated into this project.
## Table of Contents
- [Overview](#overview)
- [Security Tools](#security-tools)
- [Running Scans](#running-scans)
- [Interpreting Results](#interpreting-results)
- [Remediation](#remediation)
- [CI/CD Integration](#cicd-integration)
## Overview
The project integrates 5 security scanning tools to ensure code quality and security:
1. **SolidityScan** - Solidity-specific security scanner
2. **Slither** - Static analysis framework for Solidity
3. **Mythril** - Security analysis tool for Ethereum smart contracts
4. **Snyk** - Dependency vulnerability scanner
5. **Trivy** - Container image vulnerability scanner
## Security Tools
### 1. SolidityScan
**Purpose**: Solidity-specific security vulnerabilities
**Usage**:
```bash
# Run SolidityScan
npm run security:solidityscan
# Or directly
npx @solidityscan/cli scan contracts/
```
**Output**: HTML report with vulnerabilities and recommendations
### 2. Slither
**Purpose**: Static analysis for Solidity contracts
**Usage**:
```bash
# Run Slither
slither contracts/
# With specific detectors
slither contracts/ --detect all
```
**Output**: Console output and JSON report
### 3. Mythril
**Purpose**: Security analysis using symbolic execution
**Usage**:
```bash
# Run Mythril
myth analyze contracts/ContractName.sol
# With options
myth analyze contracts/ContractName.sol --execution-timeout 300
```
**Output**: Security issues and recommendations
### 4. Snyk
**Purpose**: Dependency vulnerability scanning
**Usage**:
```bash
# Test dependencies
snyk test
# Monitor dependencies
snyk monitor
# Test container images
snyk container test <image>
```
**Output**: Vulnerability report with severity levels
### 5. Trivy
**Purpose**: Container image vulnerability scanning
**Usage**:
```bash
# Scan container image
trivy image <image-name>
# Scan filesystem
trivy fs .
# Scan repository
trivy repo <repo-url>
```
**Output**: Vulnerability report with CVSS scores
## Running Scans
### Complete Security Scan
```bash
# Run all security scans
make security-scan
# Or individually
make security:solidityscan
make security:slither
make security:mythril
make security:snyk
make security:trivy
```
### Contract-Specific Scans
```bash
# Scan specific contract
slither contracts/OracleAggregator.sol
myth analyze contracts/OracleAggregator.sol
```
### CI/CD Integration
Scans can be integrated into CI/CD pipelines:
```yaml
# Example GitHub Actions
- name: Run Security Scans
run: |
make security-scan
```
## Interpreting Results
### Severity Levels
- **Critical**: Immediate action required
- **High**: Should be addressed soon
- **Medium**: Should be addressed when possible
- **Low**: Consider addressing
- **Info**: Informational only
### Common Issues
#### Reentrancy
- **Tool**: Slither, Mythril
- **Severity**: High/Critical
- **Description**: Contract vulnerable to reentrancy attacks
#### Unchecked External Calls
- **Tool**: Slither
- **Severity**: Medium/High
- **Description**: External calls without proper checks
#### Integer Overflow/Underflow
- **Tool**: Slither, Mythril
- **Severity**: Medium
- **Description**: Potential integer overflow/underflow
#### Access Control Issues
- **Tool**: Slither
- **Severity**: High
- **Description**: Missing or incorrect access controls
## Remediation
### Fixing Issues
1. **Review the issue**: Understand the vulnerability
2. **Assess impact**: Determine severity and impact
3. **Fix the code**: Implement the fix
4. **Re-scan**: Verify the fix resolved the issue
5. **Test**: Run tests to ensure functionality
### Example Fixes
#### Reentrancy Protection
```solidity
// Before (vulnerable)
function withdraw() external {
uint amount = balances[msg.sender];
(bool success, ) = msg.sender.call{value: amount}("");
balances[msg.sender] = 0;
}
// After (protected)
function withdraw() external {
uint amount = balances[msg.sender];
balances[msg.sender] = 0; // Update state first
(bool success, ) = msg.sender.call{value: amount}("");
}
```
## CI/CD Integration
### GitHub Actions Example
```yaml
name: Security Scan
on: [push, pull_request]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run Slither
run: slither contracts/
- name: Run Snyk
run: snyk test
```
## Best Practices
1. **Run scans regularly**: Before commits and in CI/CD
2. **Fix critical issues immediately**: Don't deploy with critical vulnerabilities
3. **Review all findings**: Not all findings are actual vulnerabilities
4. **Keep tools updated**: Use latest versions for best detection
5. **Document exceptions**: If a finding is a false positive, document why
## Related Documentation
- [Security Documentation](SECURITY.md)
- [Master Documentation Index](../MASTER_DOCUMENTATION_INDEX.md)
---
**Last Updated**: 2025-01-27

159
docs/security/SECURITY_SCORES.md Normal file
View File

@@ -0,0 +1,159 @@
# Security Score Interpretation
## Overview
This document explains how to interpret security scores from various scanning tools.
## SolidityScan Scores
### Score Range: 0-100
**90-100 (Excellent)**
- Production ready
- Minimal security risks
- Follows best practices
- No critical vulnerabilities
**70-89 (Good)**
- Minor improvements recommended
- Some security concerns
- Should address medium-severity issues
- Generally safe for production
**50-69 (Fair)**
- Should address issues before production
- Multiple security concerns
- Review high-severity issues
- Consider security audit
**0-49 (Poor)**
- Must fix before production
- Critical security vulnerabilities
- Significant security risks
- Requires immediate attention
## Common Vulnerabilities
### Critical (Score Impact: -20 to -50)
1. **Reentrancy**: Unauthorized external calls
2. **Integer Overflow**: Arithmetic operations
3. **Access Control**: Unauthorized access
4. **Unchecked External Calls**: Missing error handling
### High (Score Impact: -10 to -20)
1. **Gas Optimization**: Inefficient code
2. **Timestamp Dependence**: Block timestamp usage
3. **Front-running**: Transaction ordering
4. **Denial of Service**: Resource exhaustion
### Medium (Score Impact: -5 to -10)
1. **Code Quality**: Best practices
2. **Documentation**: Missing comments
3. **Error Handling**: Incomplete error handling
4. **Event Logging**: Missing events
### Low (Score Impact: -1 to -5)
1. **Naming Conventions**: Style issues
2. **Code Duplication**: Repeated code
3. **Unused Variables**: Dead code
4. **Style Issues**: Formatting
## Improving Scores
### Quick Wins
1. **Fix Critical Issues**: Address reentrancy, overflow
2. **Add Access Control**: Implement proper permissions
3. **Error Handling**: Add require/assert statements
4. **Events**: Emit events for important actions
### Medium-Term
1. **Code Review**: Regular security reviews
2. **Testing**: Comprehensive test coverage
3. **Documentation**: Document security decisions
4. **Best Practices**: Follow Solidity best practices
### Long-Term
1. **Security Audits**: Regular professional audits
2. **Formal Verification**: Mathematical proofs
3. **Bug Bounties**: Community security testing
4. **Continuous Improvement**: Ongoing security work
## Score Tracking
### Baseline
Establish baseline scores for:
- New contracts: Target 90+
- Existing contracts: Improve gradually
- Critical contracts: Must be 95+
### Trends
Monitor score trends:
- Improving: Good progress
- Stable: Maintain current level
- Declining: Investigate and fix
### Goals
Set score goals:
- **Q1**: Average score 80+
- **Q2**: Average score 85+
- **Q3**: Average score 90+
- **Q4**: Average score 95+
## Integration with CI/CD
### Score Thresholds
Set minimum score thresholds:
```yaml
# In CI/CD pipeline
- name: Check Security Score
run: |
SCORE=$(solidityscan --api-key $API_KEY --project-path . --format json | jq '.score')
if [ $SCORE -lt 80 ]; then
echo "Security score $SCORE is below threshold 80"
exit 1
fi
```
### Blocking Deployments
Block deployments if:
- Score < 70 for critical contracts
- Score < 80 for new contracts
- Critical vulnerabilities present
## Reporting
### Dashboard
View scores in:
- SolidityScan dashboard
- Blockscout UI
- CI/CD reports
- Security dashboard
### Alerts
Set up alerts for:
- Score drops below threshold
- New critical vulnerabilities
- Score improvements
- Scan failures
## References
- [SolidityScan Documentation](https://docs.solidityscan.com)
- [Security Scanning Process](docs/SECURITY_SCANNING.md)
- [Security Best Practices](docs/SECURITY.md)

191
docs/security/SOLIDITYSCAN_SETUP.md Normal file
View File

@@ -0,0 +1,191 @@
# SolidityScan Setup Guide
## Overview
This guide explains how to set up and configure SolidityScan for automated contract vulnerability scanning.
## Prerequisites
- SolidityScan account (sign up at https://solidityscan.com)
- API key from SolidityScan
- Access to Blockscout configuration
## Step 1: Create SolidityScan Account
1. Visit https://solidityscan.com
2. Sign up for an account
3. Navigate to API Keys section
4. Generate a new API key
5. Copy the API key (you'll need it later)
## Step 2: Configure API Key
### Kubernetes Secret
Create a Kubernetes secret with the API key:
```bash
kubectl create secret generic solidityscan-secrets \
--from-literal=api-key='<your-api-key>' \
-n besu-network
```
### Update Deployment
The secret is referenced in `k8s/blockscout/solidityscan-integration.yaml`:
```yaml
env:
- name: SOLIDITYSCAN_API_KEY
valueFrom:
secretKeyRef:
name: solidityscan-secrets
key: api-key
```
## Step 3: Deploy SolidityScan Integration
```bash
# Apply SolidityScan integration
kubectl apply -f k8s/blockscout/solidityscan-integration.yaml
# Verify deployment
kubectl get pods -n besu-network -l app=solidityscan
```
## Step 4: Configure Blockscout
### Enable SolidityScan in Blockscout
Update Blockscout configuration to enable SolidityScan:
```yaml
# In k8s/blockscout/deployment.yaml
env:
- name: ENABLE_SOLIDITYSCAN
value: "true"
- name: SOLIDITYSCAN_API_KEY
valueFrom:
secretKeyRef:
name: solidityscan-secrets
key: api-key
```
## Step 5: Configure Automatic Scanning
### Enable Auto-Scan on Verification
Configure Blockscout to automatically scan contracts when verified:
```yaml
env:
- name: SOLIDITYSCAN_AUTO_SCAN
value: "true"
```
## Step 6: Configure Webhooks (Optional)
Set up webhook notifications for vulnerabilities:
1. In SolidityScan dashboard, configure webhook URL
2. Update Blockscout configuration with webhook URL
```yaml
env:
- name: SOLIDITYSCAN_WEBHOOK_URL
value: "https://your-webhook-url.com/vulnerabilities"
```
## Step 7: Verify Setup
### Test Scanning
1. Deploy a test contract
2. Verify the contract in Blockscout
3. Check SolidityScan dashboard for scan results
4. Verify security score is displayed in Blockscout
### Check Logs
```bash
# Check Blockscout logs
kubectl logs -n besu-network -l app=blockscout | grep solidityscan
# Check SolidityScan integration logs
kubectl logs -n besu-network -l app=solidityscan
```
## CI/CD Integration
### GitHub Actions
The CI/CD pipeline includes SolidityScan:
```yaml
- name: Run SolidityScan
if: ${{ secrets.SOLIDITYSCAN_API_KEY != '' }}
run: |
pip install solidityscan
solidityscan --api-key ${{ secrets.SOLIDITYSCAN_API_KEY }} --project-path .
```
### Add Secret to GitHub
1. Go to repository Settings > Secrets
2. Add `SOLIDITYSCAN_API_KEY` secret
3. CI/CD will automatically run SolidityScan on commits
## Security Score Display
Security scores are displayed in Blockscout contract pages:
- **Score 90-100**: Excellent (Green)
- **Score 70-89**: Good (Yellow)
- **Score 50-69**: Fair (Orange)
- **Score 0-49**: Poor (Red)
## Troubleshooting
### API Key Invalid
**Error**: "Invalid API key"
**Solution**:
1. Verify API key is correct
2. Check API key hasn't expired
3. Regenerate API key if needed
### Scan Not Running
**Error**: "Scan not triggered"
**Solution**:
1. Check Blockscout configuration
2. Verify auto-scan is enabled
3. Check SolidityScan integration pod logs
4. Verify API key is set correctly
### Webhook Not Working
**Error**: "Webhook not receiving notifications"
**Solution**:
1. Verify webhook URL is accessible
2. Check webhook URL format
3. Test webhook endpoint manually
4. Check firewall rules
## Best Practices
1. **Regular Scanning**: Scan all contracts before deployment
2. **Review Scores**: Review security scores before production
3. **Fix Issues**: Address high-severity issues immediately
4. **Monitor**: Set up alerts for critical vulnerabilities
5. **Documentation**: Document security decisions
## References
- [SolidityScan Documentation](https://docs.solidityscan.com)
- [SolidityScan Dashboard](https://solidityscan.com)
- [Blockscout Integration](https://docs.blockscout.com)