shieldcortex 4.9.1 → 4.10.1

package/dist/environment/index.js

@@ -0,0 +1,5 @@
+export { scanUrl } from './scanner.js';
+export { scoreProvenance } from './provenance.js';
+export { analyseHidden } from './hidden-detector.js';
+export { deriveTaint } from './taint.js';
+export { formatEnvScanReport, formatEnvScanMarkdown } from './report.js';

package/dist/environment/provenance.d.ts

@@ -0,0 +1,6 @@
+import type { ProvenanceResult } from './types.js';
+export declare function scoreProvenance(args: {
+    originalUrl: string;
+    finalUrl: string;
+    redirectChain: string[];
+}): ProvenanceResult;

package/dist/environment/provenance.js

@@ -0,0 +1,127 @@
+const SUSPICIOUS_TLDS = new Set([
+    'zip', 'mov', 'top', 'xyz', 'click', 'country', 'link', 'gq', 'ml', 'tk', 'cf', 'ga',
+    'quest', 'sbs', 'rest', 'cyou', 'bond', 'cam', 'cfd', 'trade', 'download', 'racing',
+]);
+const KNOWN_GOOD_DOMAINS = new Set([
+    'github.com', 'raw.githubusercontent.com', 'gitlab.com', 'bitbucket.org',
+    'npmjs.com', 'registry.npmjs.org', 'pypi.org', 'rubygems.org', 'crates.io',
+    'anthropic.com', 'openai.com', 'google.com', 'cloudflare.com',
+    'stripe.com', 'mozilla.org', 'w3.org', 'ietf.org', 'python.org',
+    'rust-lang.org', 'golang.org', 'nodejs.org', 'typescriptlang.org',
+    'arxiv.org', 'wikipedia.org', 'wikimedia.org',
+    'shieldcortex.ai', 'drakonsystems.com',
+]);
+const KNOWN_BAD_DOMAINS = new Set([
+// intentionally empty — populated from threat feeds in later phases
+]);
+function extractRegistrableDomain(hostname) {
+    const parts = hostname.toLowerCase().split('.');
+    if (parts.length <= 2)
+        return hostname.toLowerCase();
+    return parts.slice(-2).join('.');
+}
+function isIpAddress(hostname) {
+    return /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname) || /:/.test(hostname);
+}
+function hasPunycode(hostname) {
+    return /xn--/i.test(hostname);
+}
+export function scoreProvenance(args) {
+    const reasons = [];
+    let score = 0.5;
+    let finalParsed;
+    try {
+        finalParsed = new URL(args.finalUrl);
+    }
+    catch {
+        return {
+            score: 0,
+            signals: {
+                tls: false,
+                redirectCount: args.redirectChain.length,
+                redirectChain: args.redirectChain,
+                finalDomain: '',
+                suspiciousTld: false,
+                allowlisted: false,
+                denylisted: false,
+                isIpAddress: false,
+                hasUserInfo: false,
+                hasPunycode: false,
+            },
+            reasons: ['Unparseable final URL'],
+        };
+    }
+    const tls = finalParsed.protocol === 'https:';
+    const finalDomain = extractRegistrableDomain(finalParsed.hostname);
+    const tld = finalDomain.split('.').pop() || '';
+    const suspiciousTld = SUSPICIOUS_TLDS.has(tld);
+    const allowlisted = KNOWN_GOOD_DOMAINS.has(finalDomain) || KNOWN_GOOD_DOMAINS.has(finalParsed.hostname);
+    const denylisted = KNOWN_BAD_DOMAINS.has(finalDomain) || KNOWN_BAD_DOMAINS.has(finalParsed.hostname);
+    const ipHost = isIpAddress(finalParsed.hostname);
+    const userInfo = Boolean(finalParsed.username || finalParsed.password);
+    const punycode = hasPunycode(finalParsed.hostname);
+    if (tls) {
+        score += 0.1;
+        reasons.push('TLS connection');
+    }
+    else {
+        score -= 0.25;
+        reasons.push('Plain HTTP (no TLS)');
+    }
+    if (allowlisted) {
+        score += 0.3;
+        reasons.push(`Allowlisted domain: ${finalDomain}`);
+    }
+    if (denylisted) {
+        score -= 0.8;
+        reasons.push(`Denylisted domain: ${finalDomain}`);
+    }
+    if (suspiciousTld) {
+        score -= 0.2;
+        reasons.push(`Suspicious TLD: .${tld}`);
+    }
+    if (ipHost) {
+        score -= 0.15;
+        reasons.push('Host is raw IP address');
+    }
+    if (userInfo) {
+        score -= 0.3;
+        reasons.push('URL contains embedded credentials');
+    }
+    if (punycode) {
+        score -= 0.1;
+        reasons.push('Host uses Punycode (possible homograph attack)');
+    }
+    if (args.redirectChain.length > 0) {
+        const originalDomain = (() => {
+            try {
+                return extractRegistrableDomain(new URL(args.originalUrl).hostname);
+            }
+            catch {
+                return '';
+            }
+        })();
+        if (originalDomain && originalDomain !== finalDomain) {
+            score -= 0.1;
+            reasons.push(`Cross-domain redirect: ${originalDomain} → ${finalDomain}`);
+        }
+        if (args.redirectChain.length >= 3) {
+            score -= 0.1;
+            reasons.push(`${args.redirectChain.length} redirects before final response`);
+        }
+    }
+    score = Math.max(0, Math.min(1, score));
+    const signals = {
+        tls,
+        redirectCount: args.redirectChain.length,
+        redirectChain: args.redirectChain,
+        finalDomain,
+        suspiciousTld,
+        allowlisted,
+        denylisted,
+        isIpAddress: ipHost,
+        hasUserInfo: userInfo,
+        hasPunycode: punycode,
+    };
+    return { score, signals, reasons };
+}

package/dist/environment/report.d.ts

@@ -0,0 +1,3 @@
+import type { EnvironmentScanResult } from './types.js';
+export declare function formatEnvScanReport(result: EnvironmentScanResult): string;
+export declare function formatEnvScanMarkdown(result: EnvironmentScanResult): string;

package/dist/environment/report.js

@@ -0,0 +1,89 @@
+const TAINT_COLOURS = {
+    trusted: '\x1b[32m',
+    untrusted: '\x1b[33m',
+    suspicious: '\x1b[91m',
+    hostile: '\x1b[31m',
+};
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+export function formatEnvScanReport(result) {
+    const lines = [];
+    const colour = TAINT_COLOURS[result.taint.label];
+    lines.push('');
+    lines.push(`${BOLD}Environment Firewall Report${RESET}`);
+    lines.push('─'.repeat(60));
+    lines.push(`  URL:          ${result.url}`);
+    if (result.finalUrl !== result.url)
+        lines.push(`  Final URL:    ${result.finalUrl}`);
+    lines.push(`  Status:       ${result.statusCode ?? 'n/a'} (${result.bytesReceived} bytes, ${result.fetchDurationMs}ms)`);
+    lines.push(`  Taint:        ${colour}${result.taint.label.toUpperCase()}${RESET} — ${result.taint.reason}`);
+    lines.push(`  Provenance:   ${result.provenance.score.toFixed(2)} (${result.provenance.signals.finalDomain})`);
+    if (result.provenance.reasons.length > 0) {
+        lines.push(`\n${BOLD}Provenance signals:${RESET}`);
+        for (const r of result.provenance.reasons)
+            lines.push(`  - ${r}`);
+    }
+    if (result.hidden.hits.length > 0) {
+        lines.push(`\n${BOLD}Hidden content (${result.hidden.hits.length}):${RESET}`);
+        const grouped = new Map();
+        for (const h of result.hidden.hits)
+            grouped.set(h.technique, (grouped.get(h.technique) ?? 0) + 1);
+        for (const [technique, count] of grouped)
+            lines.push(`  - ${technique}: ${count}`);
+    }
+    if (result.injection.visibleHits.length > 0 || result.injection.hiddenHits.length > 0) {
+        lines.push(`\n${BOLD}Injection patterns:${RESET}`);
+        for (const hit of [...result.injection.hiddenHits, ...result.injection.visibleHits]) {
+            const surfaceTag = hit.surface === 'hidden' ? `${TAINT_COLOURS.hostile}[HIDDEN]${RESET}` : `${DIM}[visible]${RESET}`;
+            lines.push(`  ${surfaceTag} ${hit.pattern}: "${hit.snippet.slice(0, 80)}"`);
+        }
+    }
+    if (result.risks.length > 0) {
+        lines.push(`\n${BOLD}Risks:${RESET}`);
+        for (const r of result.risks)
+            lines.push(`  - ${r}`);
+    }
+    lines.push('');
+    lines.push(result.summary);
+    lines.push('');
+    return lines.join('\n');
+}
+export function formatEnvScanMarkdown(result) {
+    const lines = [];
+    lines.push(`# Environment Firewall Report`);
+    lines.push('');
+    lines.push(`- **URL**: ${result.url}`);
+    if (result.finalUrl !== result.url)
+        lines.push(`- **Final URL**: ${result.finalUrl}`);
+    lines.push(`- **Status**: ${result.statusCode ?? 'n/a'} (${result.bytesReceived} bytes, ${result.fetchDurationMs}ms)`);
+    lines.push(`- **Taint**: \`${result.taint.label.toUpperCase()}\` — ${result.taint.reason}`);
+    lines.push(`- **Provenance score**: ${result.provenance.score.toFixed(2)} (${result.provenance.signals.finalDomain})`);
+    if (result.provenance.reasons.length > 0) {
+        lines.push('');
+        lines.push('## Provenance signals');
+        for (const r of result.provenance.reasons)
+            lines.push(`- ${r}`);
+    }
+    if (result.hidden.hits.length > 0) {
+        lines.push('');
+        lines.push('## Hidden content');
+        for (const h of result.hidden.hits) {
+            lines.push(`- \`${h.technique}\` (${h.charCount} chars): ${h.sample}`);
+        }
+    }
+    if (result.injection.visibleHits.length > 0 || result.injection.hiddenHits.length > 0) {
+        lines.push('');
+        lines.push('## Injection patterns');
+        for (const hit of [...result.injection.hiddenHits, ...result.injection.visibleHits]) {
+            lines.push(`- **[${hit.surface}]** \`${hit.pattern}\`: "${hit.snippet.slice(0, 120)}"`);
+        }
+    }
+    if (result.risks.length > 0) {
+        lines.push('');
+        lines.push('## Risks');
+        for (const r of result.risks)
+            lines.push(`- ${r}`);
+    }
+    return lines.join('\n');
+}

package/dist/environment/scanner.d.ts

@@ -0,0 +1,2 @@
+import type { EnvironmentScanResult } from './types.js';
+export declare function scanUrl(url: string): Promise<EnvironmentScanResult>;

package/dist/environment/scanner.js

@@ -0,0 +1,119 @@
+import { scanForInjection } from '../defence/iron-dome/injection-scanner.js';
+import { fetchWithProvenance } from './fetcher.js';
+import { scoreProvenance } from './provenance.js';
+import { analyseHidden } from './hidden-detector.js';
+import { deriveTaint } from './taint.js';
+function toHits(detections, surface) {
+    return detections.map((d) => ({
+        surface,
+        pattern: `${d.category}/${d.pattern}`,
+        snippet: d.match,
+    }));
+}
+function buildRisks(args) {
+    const risks = [];
+    if (args.hiddenHits.length > 0) {
+        risks.push(`${args.hiddenHits.length} injection pattern${args.hiddenHits.length === 1 ? '' : 's'} found in HIDDEN content — humans will never see this.`);
+    }
+    if (args.visibleHits.length > 0) {
+        risks.push(`${args.visibleHits.length} injection pattern${args.visibleHits.length === 1 ? '' : 's'} found in visible content.`);
+    }
+    const htmlComments = args.hidden.hits.filter((h) => h.technique === 'html_comment');
+    if (htmlComments.length > 0) {
+        risks.push(`${htmlComments.length} substantial HTML comment${htmlComments.length === 1 ? '' : 's'} — review for hidden agent instructions.`);
+    }
+    const layoutHides = args.hidden.hits.filter((h) => ['display_none', 'visibility_hidden', 'zero_font_size', 'offscreen_position', 'same_colour_text'].includes(h.technique));
+    if (layoutHides.length > 0) {
+        risks.push(`${layoutHides.length} CSS-hidden text region${layoutHides.length === 1 ? '' : 's'} — content visible to an agent parser but not a human reader.`);
+    }
+    if (args.hidden.hits.some((h) => h.technique === 'bidi_override')) {
+        risks.push('Unicode bidi override characters found — possible rendering-vs-parsing deception.');
+    }
+    if (args.hidden.hits.some((h) => h.technique === 'meta_refresh')) {
+        risks.push('Meta refresh redirect in document — agent may be steered to a different page.');
+    }
+    if (args.hidden.hits.some((h) => h.technique === 'zero_width_text')) {
+        risks.push('Zero-width characters in document — possible obfuscation or watermark.');
+    }
+    if (!args.provenance.signals.tls)
+        risks.push('Fetched over plain HTTP — content integrity not verified.');
+    if (args.provenance.signals.denylisted)
+        risks.push(`Final domain is denylisted: ${args.provenance.signals.finalDomain}.`);
+    if (args.provenance.signals.suspiciousTld)
+        risks.push(`Final domain uses a suspicious TLD (.${args.provenance.signals.finalDomain.split('.').pop()}).`);
+    if (args.provenance.signals.hasPunycode)
+        risks.push('Domain uses Punycode — possible homograph attack against a known brand.');
+    if (args.provenance.signals.isIpAddress)
+        risks.push('Request went to a raw IP address rather than a domain name.');
+    if (args.statusCode && args.statusCode >= 400)
+        risks.push(`HTTP ${args.statusCode} — response may be an error page rather than the intended content.`);
+    return risks;
+}
+function buildSummary(result) {
+    const lines = [];
+    lines.push(`Taint: ${result.taint.label.toUpperCase()} — ${result.taint.reason}`);
+    lines.push(`Provenance score: ${result.provenance.score.toFixed(2)} (${result.provenance.signals.finalDomain})`);
+    lines.push(`Visible injection hits: ${result.injection.visibleHits.length}`);
+    lines.push(`Hidden injection hits: ${result.injection.hiddenHits.length}`);
+    lines.push(`Hidden content techniques: ${result.hidden.hits.length > 0 ? Array.from(new Set(result.hidden.hits.map((h) => h.technique))).join(', ') : 'none'}`);
+    return lines.join('\n');
+}
+export async function scanUrl(url) {
+    const fetched = await fetchWithProvenance(url);
+    const provenance = scoreProvenance({
+        originalUrl: url,
+        finalUrl: fetched.finalUrl,
+        redirectChain: fetched.redirectChain,
+    });
+    if (fetched.error || !fetched.body) {
+        const hidden = { hits: [], hiddenCharCount: 0, visibleText: '', hiddenText: '' };
+        const injection = { visibleHits: [], hiddenHits: [] };
+        const taint = deriveTaint({ provenance, hidden, visibleHits: [], hiddenHits: [] });
+        const risks = buildRisks({ provenance, hidden, visibleHits: [], hiddenHits: [], statusCode: fetched.statusCode });
+        if (fetched.error)
+            risks.unshift(`Fetch failed: ${fetched.error}`);
+        const partial = { taint, provenance, injection, hidden, finalUrl: fetched.finalUrl };
+        return {
+            url,
+            finalUrl: fetched.finalUrl,
+            statusCode: fetched.statusCode,
+            contentType: fetched.contentType,
+            fetchedAt: new Date().toISOString(),
+            fetchDurationMs: fetched.durationMs,
+            bytesReceived: fetched.bytesReceived,
+            error: fetched.error,
+            provenance,
+            hidden,
+            injection,
+            taint,
+            risks,
+            summary: buildSummary(partial),
+        };
+    }
+    const hidden = analyseHidden(fetched.body);
+    const visibleScan = scanForInjection(hidden.visibleText);
+    const hiddenScan = scanForInjection(hidden.hiddenText);
+    const injection = {
+        visibleHits: toHits(visibleScan.detections, 'visible'),
+        hiddenHits: toHits(hiddenScan.detections, 'hidden'),
+    };
+    const taint = deriveTaint({ provenance, hidden, visibleHits: injection.visibleHits, hiddenHits: injection.hiddenHits });
+    const risks = buildRisks({ provenance, hidden, visibleHits: injection.visibleHits, hiddenHits: injection.hiddenHits, statusCode: fetched.statusCode });
+    const partial = { taint, provenance, injection, hidden, finalUrl: fetched.finalUrl };
+    return {
+        url,
+        finalUrl: fetched.finalUrl,
+        statusCode: fetched.statusCode,
+        contentType: fetched.contentType,
+        fetchedAt: new Date().toISOString(),
+        fetchDurationMs: fetched.durationMs,
+        bytesReceived: fetched.bytesReceived,
+        error: null,
+        provenance,
+        hidden,
+        injection,
+        taint,
+        risks,
+        summary: buildSummary(partial),
+    };
+}

package/dist/environment/taint.d.ts

@@ -0,0 +1,10 @@
+import type { HiddenAnalysis, InjectionHit, ProvenanceResult, TaintLabel } from './types.js';
+export declare function deriveTaint(args: {
+    provenance: ProvenanceResult;
+    hidden: HiddenAnalysis;
+    visibleHits: InjectionHit[];
+    hiddenHits: InjectionHit[];
+}): {
+    label: TaintLabel;
+    reason: string;
+};

package/dist/environment/taint.js

@@ -0,0 +1,43 @@
+export function deriveTaint(args) {
+    const { provenance, hidden, visibleHits, hiddenHits } = args;
+    if (provenance.signals.denylisted) {
+        return { label: 'hostile', reason: `Denylisted domain (${provenance.signals.finalDomain})` };
+    }
+    if (hiddenHits.length > 0) {
+        return {
+            label: 'hostile',
+            reason: `Injection pattern found inside hidden content (${hiddenHits.length} hit${hiddenHits.length === 1 ? '' : 's'})`,
+        };
+    }
+    if (hidden.hits.some((h) => h.technique === 'bidi_override')) {
+        return { label: 'suspicious', reason: 'Unicode bidi override characters detected (render vs parse mismatch risk)' };
+    }
+    const highRiskHidden = hidden.hits.filter((h) => h.technique === 'display_none' ||
+        h.technique === 'zero_font_size' ||
+        h.technique === 'same_colour_text' ||
+        h.technique === 'offscreen_position' ||
+        h.technique === 'visibility_hidden');
+    const highRiskHiddenChars = highRiskHidden.reduce((acc, h) => acc + h.charCount, 0);
+    if (highRiskHidden.length >= 3 || highRiskHiddenChars >= 150) {
+        return {
+            label: 'suspicious',
+            reason: `Hidden content via ${highRiskHidden[0]?.technique ?? 'layout tricks'} (${highRiskHidden.length} region${highRiskHidden.length === 1 ? '' : 's'}, ${highRiskHiddenChars} chars)`,
+        };
+    }
+    if (visibleHits.length > 0) {
+        return {
+            label: 'suspicious',
+            reason: `Injection pattern in visible content (${visibleHits.length} hit${visibleHits.length === 1 ? '' : 's'})`,
+        };
+    }
+    if (provenance.signals.allowlisted && provenance.score >= 0.7) {
+        return { label: 'trusted', reason: `Allowlisted domain (${provenance.signals.finalDomain})` };
+    }
+    if (provenance.score >= 0.6) {
+        return { label: 'untrusted', reason: `No hostile signals, provenance score ${provenance.score.toFixed(2)}` };
+    }
+    return {
+        label: 'suspicious',
+        reason: `Low provenance score (${provenance.score.toFixed(2)}): ${provenance.reasons.slice(0, 2).join('; ')}`,
+    };
+}

package/dist/environment/types.d.ts

@@ -0,0 +1,56 @@
+export type TaintLabel = 'trusted' | 'untrusted' | 'suspicious' | 'hostile';
+export interface ProvenanceSignals {
+    tls: boolean;
+    redirectCount: number;
+    redirectChain: string[];
+    finalDomain: string;
+    suspiciousTld: boolean;
+    allowlisted: boolean;
+    denylisted: boolean;
+    isIpAddress: boolean;
+    hasUserInfo: boolean;
+    hasPunycode: boolean;
+}
+export interface ProvenanceResult {
+    score: number;
+    signals: ProvenanceSignals;
+    reasons: string[];
+}
+export interface HiddenInstructionHit {
+    technique: 'display_none' | 'visibility_hidden' | 'zero_font_size' | 'same_colour_text' | 'offscreen_position' | 'aria_hidden' | 'html_comment' | 'script_tag' | 'bidi_override' | 'zero_width_text' | 'data_attribute' | 'meta_refresh';
+    sample: string;
+    charCount: number;
+}
+export interface HiddenAnalysis {
+    hits: HiddenInstructionHit[];
+    hiddenCharCount: number;
+    visibleText: string;
+    hiddenText: string;
+}
+export interface InjectionHit {
+    surface: 'visible' | 'hidden';
+    pattern: string;
+    snippet: string;
+}
+export interface EnvironmentScanResult {
+    url: string;
+    finalUrl: string;
+    statusCode: number | null;
+    contentType: string | null;
+    fetchedAt: string;
+    fetchDurationMs: number;
+    bytesReceived: number;
+    error: string | null;
+    provenance: ProvenanceResult;
+    hidden: HiddenAnalysis;
+    injection: {
+        visibleHits: InjectionHit[];
+        hiddenHits: InjectionHit[];
+    };
+    taint: {
+        label: TaintLabel;
+        reason: string;
+    };
+    risks: string[];
+    summary: string;
+}

package/dist/environment/types.js

@@ -0,0 +1 @@
+export {};