# WebAssembly (WASM) Features in PMAT
## Table of Contents
- [Overview](#overview)
- [Quick Start](#quick-start)
- [Core Features](#core-features)
- [Usage Guide](#usage-guide)
- [Integration Examples](#integration-examples)
- [Technical Architecture](#technical-architecture)
- [API Reference](#api-reference)
## Overview
PMAT v2.77.0 introduces comprehensive WebAssembly module analysis capabilities, providing enterprise-grade quality assurance for WASM binaries. This feature suite is designed to analyze, verify, and optimize WebAssembly modules, with special support for Ruchy language notebooks and other WASM-based applications.
### Key Capabilities
- 🔍 **Deep Analysis**: Function-level complexity metrics and instruction profiling
- 🔒 **Formal Verification**: Mathematical proof of memory safety and type correctness
- 🛡️ **Security Scanning**: Pattern-based vulnerability detection
- 📊 **Performance Profiling**: Non-intrusive shadow stack profiling
- 📈 **Quality Baselines**: Multi-anchor regression detection system
## Quick Start
### Basic Analysis
```bash
# Analyze a WASM module
pmat analyze wasm module.wasm
# Output:
# WASM Analysis Summary
# ====================
# Functions: 42
# Instructions: 1337
# Binary Size: 65536 bytes
# Max Complexity: 15
```
### Complete Analysis Suite
```bash
# Run all analysis features
pmat analyze wasm module.wasm \
--verify \ # Formal verification
--security \ # Security scanning
--profile \ # Performance profiling
--baseline reference.wasm # Quality comparison
```
## Core Features
### 1. Streaming Analysis Pipeline
PMAT uses a streaming parser to handle WASM files of any size efficiently:
```rust
// Internal architecture
WasmAnalyzer {
parser: StreamingParser, // Handles GB-sized files
validator: IncrementalValidator,
profiler: ShadowStackProfiler,
detector: PatternDetector,
}
```
**Benefits:**
- Memory-efficient processing
- Real-time analysis feedback
- Support for large WASM binaries (>100MB)
- Progressive results reporting
### 2. Formal Verification
Mathematical verification of WASM module safety properties:
```bash
pmat analyze wasm module.wasm --verify
```
**Verification Checks:**
- **Memory Bounds**: All memory accesses proven within allocated bounds
- **Type Safety**: Stack operations maintain type consistency
- **Stack Balance**: Functions preserve stack discipline
- **Integer Safety**: Arithmetic operations checked for overflow
- **Control Flow**: Indirect calls validated against function table
**Example Output:**
```
Verification Result: ✅ SAFE
- Memory accesses: All bounded
- Type consistency: Maintained
- Stack balance: Verified
- Integer operations: No overflows detected
```
### 3. Security Vulnerability Scanning
Pattern-based detection of common WASM security issues:
```bash
pmat analyze wasm module.wasm --security
```
**Detected Patterns:**
| Buffer Overflow | Critical | Unchecked memory access that could exceed bounds |
| Integer Overflow | High | Arithmetic operations without overflow checks |
| Memory Growth | High | Unbounded memory.grow operations |
| Indirect Call | Medium | Unvalidated function pointer usage |
| Stack Overflow | Medium | Recursive calls without depth limits |
| Uninitialized Memory | Low | Reading memory before initialization |
**SARIF Output for CI/CD:**
```bash
pmat analyze wasm module.wasm --security --format sarif --output security.sarif
```
### 4. Performance Profiling
Non-intrusive shadow stack profiling for performance analysis:
```bash
pmat analyze wasm module.wasm --profile
```
**Profiling Metrics:**
```
Performance Profile
===================
Instruction Mix:
Control Flow: 15% (branches, loops)
Memory Ops: 25% (loads, stores)
Arithmetic: 40% (math operations)
Function Calls: 20% (direct, indirect)
Hot Functions (>5% time):
1. process_data - 18.5% (4,231 samples)
2. validate_input - 12.3% (2,812 samples)
3. compute_hash - 8.7% (1,987 samples)
Memory Profile:
Peak Usage: 4.2 MB
Growth Events: 3
Average Allocation: 256 KB
```
### 5. Quality Baselines
Compare WASM modules against reference baselines:
```bash
pmat analyze wasm current.wasm --baseline stable.wasm
```
**Multi-Anchor System:**
```yaml
Baselines:
release: # Stable production version
complexity: 15
size: 64KB
performance: 100ms
preview: # Beta version
complexity: 18
size: 68KB
performance: 95ms
experimental: # Development version
complexity: 22
size: 72KB
performance: 90ms
```
**Quality Assessment:**
```
Quality Comparison
==================
Current vs Baseline (stable.wasm):
✅ Complexity: 14 (-1, improved)
⚠️ Size: 66KB (+2KB, increased)
✅ Performance: 98ms (-2ms, faster)
Overall: PASSING (no regressions)
Recommendation: Safe to deploy
```
## Usage Guide
### Analyzing Ruchy Notebooks
Ruchy language notebooks compile to WASM for execution. PMAT provides specialized analysis:
```bash
# Analyze Ruchy notebook WASM
pmat analyze wasm ../ruchy/notebooks/data_analysis.wasm \
--verify \
--profile \
--output analysis.md
# Compare notebook versions
pmat analyze wasm ../ruchy/notebooks/v2/analysis.wasm \
--baseline ../ruchy/notebooks/v1/analysis.wasm
```
### CI/CD Integration
#### GitHub Actions
```yaml
name: WASM Quality Gate
on: [push, pull_request]
jobs:
wasm-analysis:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install PMAT
run: cargo install pmat
- name: Build WASM
run: cargo build --target wasm32-unknown-unknown
- name: Analyze WASM Security
run: |
pmat analyze wasm target/wasm32-unknown-unknown/release/app.wasm \
--security \
--format sarif \
--output wasm-security.sarif
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: wasm-security.sarif
- name: Quality Gate
run: |
pmat analyze wasm target/wasm32-unknown-unknown/release/app.wasm \
--verify \
--baseline .github/baseline.wasm
```
#### Pre-commit Hook
```bash
#!/bin/bash
# .git/hooks/pre-commit
# Check all WASM files
# Security check
pmat analyze wasm "$wasm" --security --verify
if [ $? -ne 0 ]; then
echo "❌ WASM analysis failed for $wasm"
exit 1
fi
done
echo "✅ All WASM files passed quality checks"
```
### Makefile Integration
```makefile
# WASM analysis targets
.PHONY: wasm-check wasm-security wasm-profile wasm-baseline
WASM_FILE := build/module.wasm
BASELINE_WASM := releases/stable.wasm
wasm-check: $(WASM_FILE)
@echo "Running comprehensive WASM analysis..."
pmat analyze wasm $(WASM_FILE) \
--verify \
--security \
--profile \
--baseline $(BASELINE_WASM)
wasm-security: $(WASM_FILE)
@echo "Security scanning WASM module..."
pmat analyze wasm $(WASM_FILE) \
--security \
--format sarif \
--output reports/wasm-security.sarif
wasm-profile: $(WASM_FILE)
@echo "Profiling WASM performance..."
pmat analyze wasm $(WASM_FILE) \
--profile \
--format json \
--output reports/wasm-profile.json
wasm-baseline: $(WASM_FILE)
@echo "Comparing against baseline..."
pmat analyze wasm $(WASM_FILE) \
--baseline $(BASELINE_WASM) \
--format detailed \
--verbose
```
## Integration Examples
### 1. Automated Security Scanning
```python
#!/usr/bin/env python3
"""Automated WASM security scanner"""
import subprocess
import json
import sys
def scan_wasm(wasm_file):
"""Run security scan on WASM file"""
result = subprocess.run([
'pmat', 'analyze', 'wasm', wasm_file,
'--security', '--format', 'json'
], capture_output=True, text=True)
if result.returncode != 0:
print(f"Error scanning {wasm_file}: {result.stderr}")
return None
return json.loads(result.stdout)
def main():
wasm_files = sys.argv[1:]
for wasm_file in wasm_files:
print(f"Scanning {wasm_file}...")
results = scan_wasm(wasm_file)
if results and results.get('security'):
critical = [v for v in results['security']
if v['severity'] == 'Critical']
if critical:
print(f"❌ {len(critical)} critical vulnerabilities found!")
for vuln in critical:
print(f" - {vuln['pattern']} at {vuln['location']}")
sys.exit(1)
print("✅ All WASM files passed security scan")
if __name__ == '__main__':
main()
```
### 2. Performance Regression Detection
```bash
#!/bin/bash
# detect_performance_regression.sh
CURRENT_WASM=$1
BASELINE_WASM=$2
THRESHOLD=10 # 10% regression threshold
# Run performance comparison
OUTPUT=$(pmat analyze wasm "$CURRENT_WASM" \
--profile \
--baseline "$BASELINE_WASM" \
--format json)
# Extract performance metrics
CURRENT_TIME=$(echo "$OUTPUT" | jq '.profiling.estimated_runtime_ms')
BASELINE_TIME=$(echo "$OUTPUT" | jq '.baseline.estimated_runtime_ms')
# Calculate regression percentage
REGRESSION=$(echo "scale=2; (($CURRENT_TIME - $BASELINE_TIME) / $BASELINE_TIME) * 100" | bc)
echo "Current: ${CURRENT_TIME}ms, Baseline: ${BASELINE_TIME}ms"
exit 1
fi
echo "✅ Performance acceptable: ${REGRESSION}% change"
```
### 3. Quality Dashboard Integration
```javascript
// wasm-quality-dashboard.js
const { exec } = require('child_process');
const express = require('express');
const app = express();
app.get('/api/wasm/analyze/:module', async (req, res) => {
const module = req.params.module;
exec(`pmat analyze wasm ${module} --format json`, (error, stdout) => {
if (error) {
return res.status(500).json({ error: error.message });
}
const analysis = JSON.parse(stdout);
// Calculate quality score
const score = calculateQualityScore(analysis);
res.json({
module,
score,
grade: getGrade(score),
analysis
});
});
});
function calculateQualityScore(analysis) {
let score = 100;
// Deduct for complexity
score -= Math.max(0, analysis.max_complexity - 10) * 2;
// Deduct for security issues
if (analysis.security) {
analysis.security.forEach(vuln => {
if (vuln.severity === 'Critical') score -= 10;
if (vuln.severity === 'High') score -= 5;
if (vuln.severity === 'Medium') score -= 2;
});
}
// Deduct for verification failures
if (analysis.verification && !analysis.verification.is_safe) {
score -= 20;
}
return Math.max(0, score);
}
function getGrade(score) {
if (score >= 90) return 'A+';
if (score >= 80) return 'A';
if (score >= 70) return 'B';
if (score >= 60) return 'C';
return 'F';
}
app.listen(3000, () => {
console.log('WASM Quality Dashboard running on port 3000');
});
```
## Technical Architecture
### Component Overview
```
┌─────────────────────────────────────────────┐
│ WASM Analysis Pipeline │
├─────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Binary │─────▶│ Streaming │ │
│ │ Input │ │ Parser │ │
│ └─────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Validator │ │
│ │ (Incremental) │ │
│ └─────────────────┘ │
│ │ │
│ ┌───────────────────┼───────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ │Security │ │ Profiler │ │Baseline │
│ │ Scanner │ │ Shadow │ │Comparator│
│ └──────────┘ └──────────┘ └──────────┘
│ │ │ │ │
│ └───────────────────┼───────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Output Format │ │
│ │ (JSON/SARIF) │ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────┘
```
### Key Components
1. **Streaming Parser** (`wasm/analyzer.rs`)
- Uses `wasmparser` crate for efficient parsing
- Processes modules incrementally
- Maintains minimal memory footprint
2. **Incremental Verifier** (`wasm/verifier.rs`)
- Function-by-function verification
- Shadow stack for type checking
- SMT solver integration ready
3. **Pattern Detector** (`wasm/security.rs`)
- AST pattern matching
- Vulnerability signature database
- Confidence scoring system
4. **Shadow Stack Profiler** (`wasm/profiler.rs`)
- Non-intrusive profiling
- Statistical sampling
- Call graph construction
5. **Baseline Comparator** (`wasm/baseline.rs`)
- Multi-anchor system
- Fuzzy matching for hardware differences
- Regression detection algorithms
### Performance Characteristics
| Parsing | O(n) | O(1) streaming |
| Verification | O(n*m) | O(m) per function |
| Security Scan | O(n*p) | O(p) patterns |
| Profiling | O(n*s) | O(s) samples |
| Baseline | O(n) | O(1) comparison |
Where:
- n = module size
- m = function complexity
- p = pattern count
- s = sample rate
## API Reference
### CLI Commands
#### `pmat analyze wasm`
Analyze WebAssembly modules for quality, security, and performance.
**Syntax:**
```bash
pmat analyze wasm <wasm_file> [OPTIONS]
```
**Options:**
| `--verify` | Enable formal verification | false |
| `--security` | Enable security scanning | false |
| `--profile` | Enable performance profiling | false |
| `--baseline <path>` | Compare against baseline WASM | none |
| `--format <format>` | Output format (summary/json/detailed/sarif) | summary |
| `--output <path>` | Write output to file | stdout |
| `--verbose` | Enable verbose output | false |
**Examples:**
```bash
# Basic analysis
pmat analyze wasm app.wasm
# Security focus
pmat analyze wasm app.wasm --security --format sarif
# Performance analysis
pmat analyze wasm app.wasm --profile --verbose
# Full suite
pmat analyze wasm app.wasm --verify --security --profile
```
### Output Formats
#### Summary Format
Human-readable summary of key metrics:
```
WASM Analysis Summary
====================
Functions: 42
Instructions: 1337
Binary Size: 65536 bytes
Memory Pages: 4
Max Complexity: 15
Verification: ✅ SAFE
Security: ⚠️ 3 medium issues
Performance: 95/100
```
#### JSON Format
Machine-readable complete analysis:
```json
{
"analysis": {
"function_count": 42,
"instruction_count": 1337,
"binary_size": 65536,
"memory_pages": 4,
"max_complexity": 15
},
"verification": {
"is_safe": true,
"checks": {
"memory_bounds": "passed",
"type_safety": "passed",
"stack_balance": "passed"
}
},
"security": [
{
"severity": "Medium",
"pattern": "unchecked_memory_access",
"location": "function[5]",
"confidence": 0.85
}
],
"profiling": {
"instruction_mix": {
"control_flow": 0.15,
"memory_ops": 0.25,
"arithmetic": 0.40,
"calls": 0.20
},
"hot_functions": [
{
"name": "process_data",
"percentage": 18.5,
"samples": 4231
}
]
}
}
```
#### SARIF Format
Static Analysis Results Interchange Format for CI/CD:
```json
{
"$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
"version": "2.1.0",
"runs": [{
"tool": {
"driver": {
"name": "pmat-wasm-analyzer",
"version": "2.77.0",
"rules": [...]
}
},
"results": [...]
}]
}
```
### Error Codes
| `WASM001` | Invalid WASM magic number | Ensure file is valid WASM binary |
| `WASM002` | Unsupported WASM version | Update to WASM version 1 |
| `WASM003` | Parsing error | Check WASM binary integrity |
| `WASM004` | Verification timeout | Simplify module or increase timeout |
| `WASM005` | Pattern database missing | Update PMAT installation |
## Best Practices
### 1. Regular Analysis
- Run analysis on every build
- Track metrics over time
- Set quality thresholds
### 2. Security First
- Always run security scanning
- Fix critical issues immediately
- Review medium/low issues regularly
### 3. Performance Monitoring
- Profile before optimization
- Compare against baselines
- Track regression trends
### 4. CI/CD Integration
- Automate quality gates
- Fail builds on regressions
- Generate reports for review
### 5. Baseline Management
- Maintain stable baselines
- Update baselines carefully
- Document baseline changes
## Troubleshooting
### Common Issues
**Issue: "Invalid WASM magic number"**
- Ensure file is a valid WebAssembly binary
- Check file hasn't been corrupted
- Verify build process generates WASM
**Issue: "Verification timeout"**
- Module may be too complex
- Try analyzing smaller functions
- Increase timeout with `--timeout`
**Issue: "No baseline found"**
- Ensure baseline file exists
- Check file path is correct
- Verify baseline is valid WASM
**Issue: "Security pattern not found"**
- Update PMAT to latest version
- Pattern database may be outdated
- Report issue if persists
## Related Documentation
- [WASM Analysis Guide](./wasm-analysis-guide.md) - Detailed usage guide
- [WASM Quality Assurance Specification](./specifications/components/wasm.md) - Technical specification
- [Quality Gates Guide](./quality-gates.md) - Integration with quality gates
- [MCP Integration](./mcp-integration.md) - Using WASM analysis via MCP
## Support
For issues, questions, or feature requests:
- GitHub Issues: [paiml/paiml-mcp-agent-toolkit](https://github.com/paiml/paiml-mcp-agent-toolkit/issues)
- Documentation: [docs.paiml.com](https://docs.paiml.com)
- Community: [Discord](https://discord.gg/paiml)