Skip to main content

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:

  1. Reads permissions from ~/.vaast/extensions/{id}/manifest.json
  2. Syncs to installed.json with EXACT match (no superset, no wildcards)
  3. 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​

  1. Request only what you need

    • ❌ Bad: Request http.fetch "just in case"
    • ✅ Good: Request http.fetch only if your Xtension makes outbound requests
  2. Document why each permission is needed

    • Users review permissions at install time
    • Explain in your README.md why each permission is required
  3. 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.json syncs exactly from disk manifest.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​

  1. 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)'
  2. 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.log instead)
  3. 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.com or other CDNs
  • You can't use new Function() or eval() for dynamic code
  • All HTTP requests go through VAAST's fetch proxy (respects http.fetch permission)

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:

  1. 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
  2. Test findings persistence

    • Write a finding, restart VAAST, verify it's still visible
  3. Test CSP compliance

    • Build for release (npm run build)
    • Load in VAAST release build (not dev mode)
    • Verify no CSP errors in console
  4. Test with minimal permissions

    • Start with an empty permissions: [] array
    • Add permissions one at a time until Xtension works
    • Remove any unused permissions

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);