Xtension Security Best Practices
Overview
Xtensions run in a sandboxed iframe with limited access to VAAST internals. However, improper Xtension design can still introduce security risks. This guide covers best practices for building secure Xtensions.
Permission Principle: Least Privilege
New in v0.3.6: Permissions are synced exactly from your disk manifest.json to VAAST's internal registry. No over-grants, no wildcards.
What This Means
When VAAST loads your Xtension:
- Reads permissions from
~/.vaast/extensions/{id}/manifest.json - Syncs to
installed.jsonwith EXACT match (no superset, no wildcards) - Enforces permissions at runtime via sandbox
Example: If your manifest declares ["proxy.read", "scanner.write"], your Xtension can ONLY read proxy captures and write findings. Requesting proxy.write will fail.
Best Practices
-
Request only what you need
- ❌ Bad: Request
http.fetch"just in case" - ✅ Good: Request
http.fetchonly if your Xtension makes outbound requests
- ❌ Bad: Request
-
Document why each permission is needed
- Users review permissions at install time
- Explain in your
README.mdwhy each permission is required
-
Never attempt to escalate
- Don't try to access VAAST APIs outside your declared permissions
- Escalation attempts are logged and may result in registry removal
No Capability Escalation
The Rule
Your Xtension runs with ONLY the permissions in its own manifest.json. It CANNOT:
- Access another Xtension's permissions
- Bypass the permission sandbox
- Escalate via indirect means (e.g., asking Xtriforce AI to perform privileged actions)
Why This Matters
New in v0.3.6: §11.2 permission propagation fix ensures:
installed.jsonsyncs exactly from diskmanifest.json- No over-grants (e.g., declaring
["proxy.read"]never grants["proxy.read", "proxy.write"]) - No wildcards (e.g.,
"proxy.*"is not supported)
Example vulnerability (prevented):
// ❌ WRONG: Attempting to escalate via another Xtension
api.trigger.run('sentrinel-crimson-hunter', targetUrl);
// ^ This would require the triggering Xtension to have
// the triggered Xtension's permissions. VAAST prevents this.
Correct approach:
// ✅ RIGHT: Suggest the user run another Xtension
api.scanner.addFinding({
category: 'Recommendation',
severity: 'info',
title: 'Consider running Crimson Hunter',
description: 'This endpoint may benefit from Crimson Hunter's crawler. Run it manually to discover additional surfaces.',
evidence: targetUrl,
});
Findings Persistence
New in v0.3.6: Findings written via api.scanner.addFinding() are persisted to a local SQLite database and survive app restarts.
Implications
-
Don't write sensitive data to findings
- Findings are stored locally in plaintext
- Users can export findings as JSON
- ❌ Bad:
evidence: credentials.password - ✅ Good:
evidence: 'Password field accepts weak passwords (< 8 chars)'
-
Findings are auditable
- Enterprise orgs can see all findings (including Xtension-generated)
- SOC heads audit via console.xtrinel.com
- Don't log internal Xtension state to findings (use
console.loginstead)
-
Findings are NOT encrypted
- Local SQLite database is unencrypted
- If your Xtension discovers credentials, redact them before writing
Sandboxing & CSP
New in v0.3.6: VAAST enforces split CSP (dev vs. release) and gates DevTools to debug builds.
What You Can't Do
- No inline scripts — all JavaScript must be in bundled
dist/index.js - No eval() — CSP blocks
eval(),Function(), and similar dynamic code execution - No external CDN scripts — load all dependencies via npm and bundle them
- No unsafe-inline styles — styles must be in external CSS or inline style attributes (not
<style>tags)
Why This Matters
Xtensions run in an iframe with strict CSP:
default-src 'self';
script-src 'self' 'unsafe-inline' blob: tauri://localhost;
connect-src 'self' ipc: http://ipc.localhost https://api.xtrinel.com;
What this means:
- Your bundle can't fetch scripts from
unpkg.comor other CDNs - You can't use
new Function()oreval()for dynamic code - All HTTP requests go through VAAST's fetch proxy (respects
http.fetchpermission)
HTTP Requests (http.fetch Permission)
If your Xtension needs to make outbound HTTP requests, follow these rules:
1. Only Request User-Provided or Derived URLs
❌ Bad: Hardcoded requests to third-party services
// This sends user data to an external server without consent
await fetch('https://my-logging-service.com/log', {
method: 'POST',
body: JSON.stringify({ finding: result }),
});
✅ Good: Requests to user's target or derived from scan context
// User authorized this target via domain verification
const target = api.session.getMeta().targetUrl;
await fetch(`${target}/api/check-status`, {
method: 'GET',
});
2. Disclose Third-Party Requests in Manifest Description
If your Xtension makes requests to a specific service (e.g., checking CVE databases), disclose it:
{
"description": "Checks vulnerabilities against NIST NVD API (nvd.nist.gov). Makes outbound HTTPS requests to nvd.nist.gov only.",
"permissions": ["http.fetch"]
}
3. Verify Target Authorization
New in v0.3.6: Use attestation APIs to verify target authorization before making requests.
// Check if target is attested (user declared/verified it)
const domain = extractDomain(targetUrl);
const verified = await api.targets.checkAttestation(domain);
if (!verified) {
api.scanner.addFinding({
category: 'Error',
severity: 'high',
title: 'Target not verified',
description: `Domain ${domain} is not in your verified targets list. Add it via Domain Verification before scanning.`,
evidence: targetUrl,
});
return;
}
// Safe to proceed
await fetch(targetUrl, { method: 'GET' });
Example: Secure Xtension with Findings Persistence
import type { VaastXtensionApi } from '../types/vaast-api';
export function register(api: VaastXtensionApi): void {
api.ui.registerTab('secure-scanner', 'Secure Scanner');
api.proxy.onCapture(async (capture) => {
// 1. Check permissions implicitly (proxy.read required to reach here)
// 2. Analyze capture for vulnerability
const hasWeakAuth = capture.request.headers['Authorization']?.startsWith('Bearer ') === false;
if (hasWeakAuth) {
// 3. Write finding to persistent SQLite database
await api.scanner.addFinding({
category: 'Authentication',
severity: 'medium',
title: `Weak authentication on ${capture.url}`,
description: 'Endpoint does not use Bearer token authentication. Consider implementing OAuth 2.0.',
evidence: `Request headers: ${JSON.stringify(capture.request.headers, null, 2)}`,
// ✅ GOOD: No sensitive data (passwords, tokens) in evidence
});
}
});
// 4. Never attempt to access APIs outside declared permissions
// api.proxy.write(...) would fail if not in manifest.json
}
Testing Security
Before submitting to the registry:
-
Test permission enforcement
// Remove a permission from manifest.json, rebuild, and verify the API call fails
await api.scanner.addFinding({ ... }); // Should throw if scanner.write not in manifest -
Test findings persistence
- Write a finding, restart VAAST, verify it's still visible
-
Test CSP compliance
- Build for release (
npm run build) - Load in VAAST release build (not dev mode)
- Verify no CSP errors in console
- Build for release (
-
Test with minimal permissions
- Start with an empty
permissions: []array - Add permissions one at a time until Xtension works
- Remove any unused permissions
- Start with an empty
Common Security Mistakes
1. Over-Requesting Permissions
❌ Bad:
{
"permissions": ["proxy.read", "proxy.write", "scanner.write", "http.fetch", "ui.tab"]
}
If your Xtension only reads proxy captures and writes findings, you don't need proxy.write or http.fetch.
✅ Good:
{
"permissions": ["proxy.read", "scanner.write", "ui.tab"]
}
2. Logging Sensitive Data
❌ Bad:
api.scanner.addFinding({
evidence: `Captured credentials: ${username}:${password}`,
});
✅ Good:
api.scanner.addFinding({
evidence: 'Credentials transmitted in plaintext over HTTP',
});
3. Bypassing Target Verification
❌ Bad:
// Scan any URL the user types without checking authorization
await fetch(userProvidedUrl);
✅ Good:
const domain = extractDomain(userProvidedUrl);
const verified = await api.targets.checkAttestation(domain);
if (!verified) {
throw new Error(`Target ${domain} not verified. Add it in Domain Verification first.`);
}
await fetch(userProvidedUrl);
Related Documentation
- Building Xtensions — API reference
- Manifest Reference — permission definitions
- Submitting to Registry — submission checklist