@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/static-analysis/steering/performance-tuning.md

@@ -0,0 +1,111 @@
+# Performance Tuning
+
+## Memory Configuration
+
+### CODEQL_RAM Environment Variable
+
+Control maximum heap memory (in MB):
+
+```bash
+# 48GB for large codebases
+CODEQL_RAM=48000 codeql database analyze codeql.db ...
+
+# 16GB for medium codebases
+CODEQL_RAM=16000 codeql database analyze codeql.db ...
+```
+
+**Guidelines:**
+| Codebase Size | Recommended RAM |
+|---------------|-----------------|
+| Small (<100K LOC) | 4-8 GB |
+| Medium (100K-1M LOC) | 8-16 GB |
+| Large (1M+ LOC) | 32-64 GB |
+
+## Thread Configuration
+
+### Analysis Threads
+
+```bash
+# Use all available cores
+codeql database analyze codeql.db --threads=0 ...
+
+# Use specific number
+codeql database analyze codeql.db --threads=8 ...
+```
+
+**Note:** `--threads=0` uses all available cores. For shared machines, use explicit count.
+
+## Query-Level Timeouts
+
+Prevent individual queries from running indefinitely:
+
+```bash
+# Set per-query timeout (in milliseconds)
+codeql database analyze codeql.db --timeout=600000 ...
+```
+
+A 10-minute timeout (`600000`) catches runaway queries without killing legitimate complex analysis. Taint-tracking queries on large codebases may need longer.
+
+## Evaluator Diagnostics
+
+When analysis is slow, use `--evaluator-log` to identify which queries consume the most time:
+
+```bash
+codeql database analyze codeql.db \
+  --evaluator-log=evaluator.log \
+  --format=sarif-latest \
+  --output=results.sarif \
+  -- codeql/python-queries:codeql-suites/python-security-extended.qls
+
+# Summarize the log
+codeql generate log-summary evaluator.log --format=text
+```
+
+The summary shows per-query timing and tuple counts. Queries producing millions of tuples are likely the bottleneck.
+
+## Disk Space
+
+| Phase | Typical Size | Notes |
+|-------|-------------|-------|
+| Database creation | 2-10x source size | Compiled languages are larger due to build tracing |
+| Analysis cache | 1-5 GB | Stored in database directory |
+| SARIF output | 1-50 MB | Depends on finding count |
+
+Check available space before starting:
+
+```bash
+df -h .
+du -sh codeql_*.db 2>/dev/null
+```
+
+## Caching Behavior
+
+CodeQL caches query evaluation results inside the database directory. Subsequent runs of the same queries skip re-evaluation.
+
+| Scenario | Cache Effect |
+|----------|-------------|
+| Re-run same packs | Fast — uses cached results |
+| Add new query pack | Only new queries evaluate |
+| `codeql database cleanup` | Clears cache — forces full re-evaluation |
+| `--rerun` flag | Ignores cache for this run |
+
+**When to clear cache:**
+- After deploying new data extensions (cache may hold stale results)
+- When investigating unexpected zero-finding results
+- Before benchmark comparisons (ensures consistent timing)
+
+```bash
+# Clear evaluation cache
+codeql database cleanup codeql_1.db
+```
+
+## Troubleshooting Performance
+
+| Symptom | Likely Cause | Solution |
+|---------|--------------|----------|
+| OOM during analysis | Not enough RAM | Increase `CODEQL_RAM` |
+| Slow database creation | Complex build | Use `--threads`, simplify build |
+| Slow query execution | Large codebase | Reduce query scope, add RAM |
+| Database too large | Too many files | Use exclusion config (see [build-database workflow](../workflows/build-database.md#1b-create-exclusion-config-interpreted-languages-only)) |
+| Single query hangs | Runaway evaluation | Use `--timeout` and check `--evaluator-log` |
+| Repeated runs still slow | Cache not used | Check you're using same database path |

package/Ai Agent Workflow/powers/static-analysis/steering/ruleset-catalog.md

@@ -0,0 +1,63 @@
+# Ruleset Catalog
+
+## Official CodeQL Suites
+
+| Suite | False Positives | Use Case |
+|-------|-----------------|----------|
+| `security-extended` | Low | **Default** - Security audits |
+| `security-and-quality` | Medium | Comprehensive review |
+| `security-experimental` | Higher | Research, vulnerability hunting |
+
+**Usage:** `codeql/<lang>-queries:codeql-suites/<lang>-security-extended.qls`
+
+**Languages:** `cpp`, `csharp`, `go`, `java`, `javascript`, `python`, `ruby`, `swift`
+
+---
+
+## Trail of Bits Packs
+
+| Pack | Language | Focus |
+|------|----------|-------|
+| `trailofbits/cpp-queries` | C/C++ | Memory safety, integer overflows |
+| `trailofbits/go-queries` | Go | Concurrency, error handling |
+| `trailofbits/java-queries` | Java | Security, code quality |
+
+**Install:**
+```bash
+codeql pack download trailofbits/cpp-queries
+codeql pack download trailofbits/go-queries
+codeql pack download trailofbits/java-queries
+```
+
+---
+
+## CodeQL Community Packs
+
+| Pack | Language |
+|------|----------|
+| `GitHubSecurityLab/CodeQL-Community-Packs-JavaScript` | JavaScript/TypeScript |
+| `GitHubSecurityLab/CodeQL-Community-Packs-Python` | Python |
+| `GitHubSecurityLab/CodeQL-Community-Packs-Go` | Go |
+| `GitHubSecurityLab/CodeQL-Community-Packs-Java` | Java |
+| `GitHubSecurityLab/CodeQL-Community-Packs-CPP` | C/C++ |
+| `GitHubSecurityLab/CodeQL-Community-Packs-CSharp` | C# |
+| `GitHubSecurityLab/CodeQL-Community-Packs-Ruby` | Ruby |
+
+**Install:**
+```bash
+codeql pack download GitHubSecurityLab/CodeQL-Community-Packs-<Lang>
+```
+
+**Source:** [github.com/GitHubSecurityLab/CodeQL-Community-Packs](https://github.com/GitHubSecurityLab/CodeQL-Community-Packs)
+
+---
+
+## Verify Installation
+
+```bash
+# List all installed packs
+codeql resolve qlpacks
+
+# Check specific packs
+codeql resolve qlpacks | grep -E "(trailofbits|GitHubSecurityLab)"
+```

package/Ai Agent Workflow/powers/static-analysis/steering/threat-models.md

@@ -0,0 +1,44 @@
+# Threat Models Reference
+
+Control which source categories are active during CodeQL analysis. By default, only `remote` sources are tracked.
+
+## Available Models
+
+| Model | Sources Included | When to Enable | False Positive Impact |
+|-------|------------------|----------------|----------------------|
+| `remote` | HTTP requests, network input | Always (default). Covers web services, APIs, network-facing code. | Low — these are the most common attack vectors. |
+| `local` | Command line args, local files | CLI tools, batch processors, desktop apps where local users are untrusted. | Medium — generates noise for web-only services where CLI args are developer-controlled. |
+| `environment` | Environment variables | Apps that read config from env vars at runtime (12-factor apps, containers). Skip for apps that only read env at startup into validated config objects. | Medium — many env reads are startup-only config, not runtime-tainted data. |
+| `database` | Database query results | Second-order injection scenarios: stored XSS, data from shared databases where other writers are untrusted. | High — most apps trust their own database. Only enable when auditing for stored/second-order attacks. |
+| `file` | File contents | File upload processors, log parsers, config file readers that accept user-provided files. | Medium — triggers on all file reads including trusted config files. |
+
+## Default Behavior
+
+With no `--threat-models` flag, CodeQL uses `remote` only. This is correct for most web applications and APIs. Expanding beyond `remote` is useful when the application's trust boundary extends to local inputs.
+
+## Usage
+
+Enable additional threat models with the `--threat-models` flag:
+
+```bash
+# Web service (default — remote only)
+codeql database analyze codeql.db \
+  -- codeql/python-queries
+
+# CLI tool — local users can provide malicious input
+codeql database analyze codeql.db \
+  --threat-models=remote,local \
+  -- codeql/python-queries
+
+# Container app reading env vars from untrusted orchestrator
+codeql database analyze codeql.db \
+  --threat-models=remote,environment \
+  -- codeql/python-queries
+
+# Full coverage — audit mode for all input vectors
+codeql database analyze codeql.db \
+  --threat-models=remote,local,environment,database,file \
+  -- codeql/python-queries
+```
+
+Multiple models can be combined. Each additional model expands the set of sources CodeQL considers tainted, increasing coverage but potentially increasing false positives. Start with the narrowest set that matches the application's actual threat model, then expand if needed.