@panguard-ai/threat-cloud 0.3.0 → 0.5.0

package/dist/server.js

@@ -15,6 +15,10 @@
  * - GET  /api/feeds/ip-blocklist     IP blocklist feed (text/plain, ?minReputation=)
  * - GET  /api/feeds/domain-blocklist Domain blocklist feed (text/plain, ?minReputation=)
  * - GET  /api/skill-blacklist        Community skill blacklist (aggregated threats)
+ * - POST /api/analyze-skills         Submit scan results for server-side LLM analysis
+ * - GET  /api/audit-log             Admin audit log (paginated, admin-only)
+ * - POST /api/scan-events           Report scan event from any source (bulk/CLI/web)
+ * - GET  /api/metrics               Aggregated metrics across all sources (public, cached 60s)
  * - GET  /health                     Health check
  *
  * @module @panguard-ai/threat-cloud/server
@@ -23,17 +27,25 @@ import { createServer } from 'node:http';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, basename, relative, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { randomUUID } from 'node:crypto';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
 import { ThreatCloudDB } from './database.js';
 import { LLMReviewer } from './llm-reviewer.js';
 import { getAdminHTML } from './admin-dashboard.js';
+import { tryValidateInput, ThreatDataSchema, RulePublishSchema, ATRProposalSchema, ATRFeedbackSchema, SkillThreatSchema, SkillWhitelistItemSchema, } from '@panguard-ai/core';
+import { z } from 'zod';
 /** Structured JSON logger for threat-cloud */
 const log = {
     info: (msg, extra) => {
         process.stdout.write(JSON.stringify({ ts: new Date().toISOString(), level: 'info', msg, ...extra }) + '\n');
     },
     error: (msg, err, extra) => {
-        process.stderr.write(JSON.stringify({ ts: new Date().toISOString(), level: 'error', msg, error: err instanceof Error ? err.message : String(err), ...extra }) + '\n');
+        process.stderr.write(JSON.stringify({
+            ts: new Date().toISOString(),
+            level: 'error',
+            msg,
+            error: err instanceof Error ? err.message : String(err),
+            ...extra,
+        }) + '\n');
     },
 };
 /**
@@ -152,20 +164,38 @@ export class ThreatCloudServer {
         // Rate limiting
         if (!this.checkRateLimit(clientIP)) {
             this.sendJson(res, 429, { ok: false, error: 'Rate limit exceeded', request_id: requestId });
-            log.info('request', { method: req.method, path: req.url, status: 429, duration_ms: Date.now() - startTime, client_ip: clientIP, request_id: requestId });
+            log.info('request', {
+                method: req.method,
+                path: req.url,
+                status: 429,
+                duration_ms: Date.now() - startTime,
+                client_ip: clientIP,
+                request_id: requestId,
+            });
             return;
         }
         // API key verification (skip for health check)
         const url = req.url ?? '/';
-        const rawPathname = url.split('?')[0];
+        const rawPathname = url.split('?')[0] ?? '/';
         // API versioning: strip /v1 prefix for backward compatibility
-        const pathname = rawPathname.startsWith('/v1/') ? rawPathname.slice(3) : rawPathname === '/v1' ? '/' : rawPathname;
+        const pathname = rawPathname.startsWith('/v1/')
+            ? rawPathname.slice(3)
+            : rawPathname === '/v1'
+                ? '/'
+                : rawPathname;
         if (pathname !== '/health' && this.config.apiKeyRequired) {
             const authHeader = req.headers.authorization ?? '';
             const token = authHeader.replace('Bearer ', '');
             if (!this.config.apiKeys.includes(token)) {
                 this.sendJson(res, 401, { ok: false, error: 'Invalid API key', request_id: requestId });
-                log.info('request', { method: req.method, path: rawPathname, status: 401, duration_ms: Date.now() - startTime, client_ip: clientIP, request_id: requestId });
+                log.info('request', {
+                    method: req.method,
+                    path: rawPathname,
+                    status: 401,
+                    duration_ms: Date.now() - startTime,
+                    client_ip: clientIP,
+                    request_id: requestId,
+                });
                 return;
             }
         }
@@ -181,7 +211,14 @@ export class ThreatCloudServer {
         if (req.method === 'OPTIONS') {
             res.writeHead(204);
             res.end();
-            log.info('request', { method: 'OPTIONS', path: rawPathname, status: 204, duration_ms: Date.now() - startTime, client_ip: clientIP, request_id: requestId });
+            log.info('request', {
+                method: 'OPTIONS',
+                path: rawPathname,
+                status: 204,
+                duration_ms: Date.now() - startTime,
+                client_ip: clientIP,
+                request_id: requestId,
+            });
             return;
         }
         // Store requestId on response for sendJson to include
@@ -327,6 +364,14 @@ export class ThreatCloudServer {
                         this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
                     }
                     break;
+                case '/api/analyze-skills':
+                    if (req.method === 'POST') {
+                        await this.handleAnalyzeSkills(req, res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
                 case '/api/audit-log':
                     if (req.method === 'GET') {
                         if (!this.checkAdminAuth(req)) {
@@ -339,6 +384,22 @@ export class ThreatCloudServer {
                         this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
                     }
                     break;
+                case '/api/scan-events':
+                    if (req.method === 'POST') {
+                        await this.handlePostScanEvent(req, res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
+                case '/api/metrics':
+                    if (req.method === 'GET') {
+                        this.handleGetMetrics(res);
+                    }
+                    else {
+                        this.sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+                    }
+                    break;
                 default:
                     this.sendJson(res, 404, { ok: false, error: 'Not found' });
             }
@@ -360,34 +421,36 @@ export class ThreatCloudServer {
     /** POST /api/threats - Upload anonymized threat data (single or batch) */
     async handlePostThreat(req, res) {
         const body = await this.readBody(req);
-        const parsed = JSON.parse(body);
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON body' });
+            return;
+        }
         // Support both single object and batch { events: [...] } format
-        const events = 'events' in parsed && Array.isArray(parsed.events)
-            ? parsed.events
-            : [parsed];
-        for (const data of events) {
-            // Validate required fields
-            if (!data.attackSourceIP ||
-                !data.attackType ||
-                !data.mitreTechnique ||
-                !data.sigmaRuleMatched ||
-                !data.timestamp ||
-                !data.region) {
-                this.sendJson(res, 400, {
-                    ok: false,
-                    error: 'Missing required fields: attackSourceIP, attackType, mitreTechnique, sigmaRuleMatched, timestamp, region',
-                });
+        const rawObj = raw;
+        const rawEvents = 'events' in rawObj && Array.isArray(rawObj['events']) ? rawObj['events'] : [raw];
+        const validated = [];
+        for (const event of rawEvents) {
+            const result = tryValidateInput(ThreatDataSchema, event);
+            if (!result.ok) {
+                this.sendJson(res, 400, { ok: false, error: result.error });
                 return;
             }
-            // Anonymize IP further (zero last octet if not already)
-            data.attackSourceIP = this.anonymizeIP(data.attackSourceIP);
+            const mutable = { ...result.data };
+            mutable.attackSourceIP = this.anonymizeIP(mutable.attackSourceIP);
+            validated.push(mutable);
+        }
+        for (const data of validated) {
             this.db.insertThreat(data);
         }
         const clientIP = req.socket.remoteAddress ?? 'unknown';
-        this.db.audit.logAction('client', 'threat.submit', 'threat', undefined, { count: events.length }, clientIP);
+        this.db.audit.logAction('client', 'threat.submit', 'threat', undefined, { count: validated.length }, clientIP);
         this.sendJson(res, 201, {
             ok: true,
-            data: { message: 'Threat data received', count: events.length },
+            data: { message: 'Threat data received', count: validated.length },
         });
     }
     /** GET /api/rules?since=<ISO>&category=<cat>&severity=<sev>&source=<src> */
@@ -410,16 +473,28 @@ export class ThreatCloudServer {
     /** POST /api/rules - Publish rules (single or batch) */
     async handlePostRule(req, res) {
         const body = await this.readBody(req);
-        const parsed = JSON.parse(body);
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON body' });
+            return;
+        }
         // Support both single object and batch { rules: [...] } format
-        const rules = 'rules' in parsed && Array.isArray(parsed.rules) ? parsed.rules : [parsed];
+        const rawObj = raw;
+        const rawRules = 'rules' in rawObj && Array.isArray(rawObj['rules']) ? rawObj['rules'] : [raw];
         const now = new Date().toISOString();
         let count = 0;
-        for (const rule of rules) {
-            if (!rule.ruleId || !rule.ruleContent || !rule.source)
+        for (const rawRule of rawRules) {
+            const result = tryValidateInput(RulePublishSchema, rawRule);
+            if (!result.ok)
                 continue;
-            rule.publishedAt = rule.publishedAt || now;
-            this.db.upsertRule(rule);
+            const ruleData = {
+                ...result.data,
+                publishedAt: result.data.publishedAt || now,
+            };
+            this.db.upsertRule(ruleData);
             count++;
         }
         const clientIP = req.socket.remoteAddress ?? 'unknown';
@@ -468,82 +543,57 @@ export class ThreatCloudServer {
     }
     /** POST /api/atr-proposals - Submit or confirm an ATR rule proposal */
     async handlePostATRProposal(req, res) {
-        const body = await this.readBody(req);
-        const data = JSON.parse(body);
-        const clientId = req.headers['x-panguard-client-id'] ?? undefined;
-        if (!data.patternHash || !data.ruleContent) {
-            this.sendJson(res, 400, {
-                ok: false,
-                error: 'Missing required fields: patternHash, ruleContent',
-            });
+        const data = await this.parseAndValidate(req, res, ATRProposalSchema);
+        if (!data)
             return;
-        }
+        const clientId = req.headers['x-panguard-client-id'] ?? undefined;
         // Check if a proposal with the same patternHash already exists
         const proposals = this.db.getATRProposals();
         const existing = proposals.find((p) => p['pattern_hash'] === data.patternHash);
+        const { patternHash, ruleContent } = data;
         if (existing) {
-            this.db.confirmATRProposal(data.patternHash);
+            this.db.confirmATRProposal(patternHash);
             this.sendJson(res, 200, {
                 ok: true,
-                data: { message: 'Proposal confirmed', patternHash: data.patternHash },
+                data: { message: 'Proposal confirmed', patternHash },
             });
         }
         else {
             const proposal = {
                 ...data,
-                clientId: clientId ?? data.clientId,
+                clientId,
             };
             this.db.insertATRProposal(proposal);
             // Fire-and-forget LLM review on first submission only
             if (this.llmReviewer?.isAvailable()) {
-                void this.llmReviewer.reviewProposal(data.patternHash, data.ruleContent).catch((err) => {
-                    log.error(`LLM review failed for ${data.patternHash}`, err);
+                void this.llmReviewer.reviewProposal(patternHash, ruleContent).catch((err) => {
+                    log.error(`LLM review failed for ${patternHash}`, err);
                 });
             }
             this.sendJson(res, 201, {
                 ok: true,
-                data: { message: 'Proposal submitted', patternHash: data.patternHash },
+                data: { message: 'Proposal submitted', patternHash },
             });
         }
     }
     /** POST /api/atr-feedback - Submit feedback on an ATR rule */
     async handlePostATRFeedback(req, res) {
-        const body = await this.readBody(req);
-        const data = JSON.parse(body);
-        const clientId = req.headers['x-panguard-client-id'] ?? undefined;
-        if (!data.ruleId || typeof data.isTruePositive !== 'boolean') {
-            this.sendJson(res, 400, {
-                ok: false,
-                error: 'Missing required fields: ruleId (string), isTruePositive (boolean)',
-            });
+        const data = await this.parseAndValidate(req, res, ATRFeedbackSchema);
+        if (!data)
             return;
-        }
+        const clientId = req.headers['x-panguard-client-id'] ?? undefined;
         this.db.insertATRFeedback(data.ruleId, data.isTruePositive, clientId);
         this.sendJson(res, 201, { ok: true, data: { message: 'Feedback received' } });
     }
     /** POST /api/skill-threats - Submit skill threat from audit */
     async handlePostSkillThreat(req, res) {
-        const body = await this.readBody(req);
-        const data = JSON.parse(body);
-        const clientId = req.headers['x-panguard-client-id'] ?? undefined;
-        if (!data.skillHash || !data.skillName) {
-            this.sendJson(res, 400, {
-                ok: false,
-                error: 'Missing required fields: skillHash, skillName',
-            });
-            return;
-        }
-        if (typeof data.riskScore !== 'number' || data.riskScore < 0 || data.riskScore > 100) {
-            this.sendJson(res, 400, { ok: false, error: 'riskScore must be a number between 0 and 100' });
+        const data = await this.parseAndValidate(req, res, SkillThreatSchema);
+        if (!data)
             return;
-        }
-        if (!data.riskLevel || typeof data.riskLevel !== 'string') {
-            this.sendJson(res, 400, { ok: false, error: 'riskLevel is required and must be a string' });
-            return;
-        }
+        const clientId = req.headers['x-panguard-client-id'] ?? undefined;
         const submission = {
             ...data,
-            clientId: clientId ?? data.clientId,
+            clientId,
         };
         this.db.insertSkillThreat(submission);
         const clientIP = req.socket.remoteAddress ?? 'unknown';
@@ -591,15 +641,24 @@ export class ThreatCloudServer {
     /** POST /api/skill-whitelist - Report a safe skill (audit passed) */
     async handlePostSkillWhitelist(req, res) {
         const body = await this.readBody(req);
-        const data = JSON.parse(body);
-        const skills = 'skills' in data && Array.isArray(data.skills)
-            ? data.skills
-            : [data];
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON body' });
+            return;
+        }
+        const rawObj = raw;
+        const skills = 'skills' in rawObj && Array.isArray(rawObj['skills'])
+            ? rawObj['skills']
+            : [raw];
         let count = 0;
         for (const skill of skills) {
-            if (!skill.skillName || typeof skill.skillName !== 'string')
+            const result = SkillWhitelistItemSchema.safeParse(skill);
+            if (!result.success)
                 continue;
-            this.db.reportSafeSkill(skill.skillName, skill.fingerprintHash);
+            this.db.reportSafeSkill(result.data.skillName, result.data.fingerprintHash);
             count++;
         }
         this.sendJson(res, 201, { ok: true, data: { message: `${count} skill(s) reported`, count } });
@@ -622,6 +681,59 @@ export class ThreatCloudServer {
         const blacklist = this.db.getSkillBlacklist(minReports, minAvgRisk);
         this.sendJson(res, 200, { ok: true, data: blacklist });
     }
+    /**
+     * POST /api/analyze-skills - Submit scan results for server-side LLM analysis
+     * 提交掃描結果讓伺服器端 LLM 分析語義威脅並自動產出 ATR proposals
+     *
+     * Body: { skills: [{ package: string, tools: [{ name, description }] }] }
+     * Response: { ok: true, data: { analyzed, proposalsCreated, results } }
+     */
+    async handleAnalyzeSkills(req, res) {
+        if (!this.llmReviewer?.isAvailable()) {
+            this.sendJson(res, 503, {
+                ok: false,
+                error: 'LLM reviewer not available — ANTHROPIC_API_KEY not configured on server',
+            });
+            return;
+        }
+        const AnalyzeSkillsSchema = z.object({
+            skills: z
+                .array(z.object({
+                package: z.string().min(1),
+                tools: z.array(z.object({
+                    name: z.string().min(1),
+                    description: z.string(),
+                })),
+            }))
+                .min(1, 'skills array must not be empty')
+                .max(10, 'Maximum 10 skills per request'),
+        });
+        const data = await this.parseAndValidate(req, res, AnalyzeSkillsSchema);
+        if (!data)
+            return;
+        const skills = data.skills;
+        log.info(`Analyzing ${skills.length} skills with LLM`, {
+            packages: skills.map((s) => s.package),
+        });
+        const results = await this.llmReviewer.analyzeSkills(skills);
+        const proposalsCreated = results.reduce((sum, r) => sum + r.proposals.length, 0);
+        log.info(`LLM analysis complete: ${proposalsCreated} proposals from ${skills.length} skills`);
+        this.sendJson(res, 200, {
+            ok: true,
+            data: {
+                analyzed: results.length,
+                proposalsCreated,
+                results: results.map((r) => ({
+                    package: r.package,
+                    threatsFound: r.threatsFound,
+                    proposalCount: r.proposals.length,
+                    patternHashes: r.proposals.map((p) => p.patternHash),
+                    status: r.status,
+                    ...(r.errorReason ? { errorReason: r.errorReason } : {}),
+                })),
+            },
+        });
+    }
     /** GET /api/audit-log?page=1&limit=50 (admin-only) */
     handleGetAuditLog(url, res) {
         const params = new URL(url, `http://localhost:${this.config.port}`).searchParams;
@@ -636,6 +748,32 @@ export class ThreatCloudServer {
             meta: { total, page, limit, pages: Math.ceil(total / limit) },
         });
     }
+    /** POST /api/scan-events - Report a scan event from any source */
+    async handlePostScanEvent(req, res) {
+        const ScanEventSchema = z.object({
+            source: z.enum(['bulk-pipeline', 'cli-user', 'web-scanner']),
+            skillsScanned: z.number().int().min(0),
+            findingsCount: z.number().int().min(0),
+            confirmedMalicious: z.number().int().min(0).default(0),
+            highlySuspicious: z.number().int().min(0).default(0),
+            generalSuspicious: z.number().int().min(0).default(0),
+            cleanCount: z.number().int().min(0).default(0),
+            deviceHash: z.string().optional(),
+        });
+        const data = await this.parseAndValidate(req, res, ScanEventSchema);
+        if (!data)
+            return;
+        this.db.insertScanEvent(data);
+        const clientIP = req.socket.remoteAddress ?? 'unknown';
+        this.db.audit.logAction('client', 'scan_event.submit', 'scan_event', undefined, { source: data.source, skillsScanned: data.skillsScanned }, clientIP);
+        this.sendJson(res, 201, { ok: true, data: { message: 'Scan event recorded' } });
+    }
+    /** GET /api/metrics - Aggregated metrics across all sources (public, cached 60s) */
+    handleGetMetrics(res) {
+        res.setHeader('Cache-Control', 'public, max-age=60, s-maxage=60');
+        const metrics = this.db.getAggregatedMetrics();
+        this.sendJson(res, 200, { ok: true, data: metrics });
+    }
     /** Anonymize IP by zeroing last octet / 匿名化 IP */
     anonymizeIP(ip) {
         if (ip.includes('.')) {
@@ -660,7 +798,12 @@ export class ThreatCloudServer {
             const url = new URL(req.url ?? '/', `http://localhost:${this.config.port}`);
             const queryKey = url.searchParams.get('key');
             const headerKey = (req.headers.authorization ?? '').replace('Bearer ', '');
-            if (queryKey !== this.config.adminApiKey && headerKey !== this.config.adminApiKey) {
+            const keyMatch = (candidate) => {
+                if (!candidate || candidate.length !== this.config.adminApiKey.length)
+                    return false;
+                return timingSafeEqual(Buffer.from(candidate, 'utf-8'), Buffer.from(this.config.adminApiKey, 'utf-8'));
+            };
+            if (!keyMatch(queryKey) && !keyMatch(headerKey)) {
                 res.writeHead(401, { 'Content-Type': 'text/plain' });
                 res.end('Unauthorized: admin API key required. Use ?key=YOUR_KEY or Authorization header.');
                 return;
@@ -674,11 +817,21 @@ export class ThreatCloudServer {
     }
     /** Check admin API key for write-protected endpoints / 檢查管理員 API 金鑰 */
     checkAdminAuth(req) {
-        if (!this.config.adminApiKey)
-            return true; // no admin key configured = open
+        if (!this.config.adminApiKey) {
+            // No admin key configured — only allow from loopback addresses
+            const remoteAddr = req.socket.remoteAddress ?? '';
+            const isLoopback = remoteAddr === '127.0.0.1' || remoteAddr === '::1' || remoteAddr === '::ffff:127.0.0.1';
+            if (!isLoopback) {
+                log.info(`Admin access denied: no TC_ADMIN_API_KEY configured and request from non-loopback address`, { remoteAddr });
+            }
+            return isLoopback;
+        }
         const authHeader = req.headers.authorization ?? '';
         const token = authHeader.replace('Bearer ', '');
-        return token === this.config.adminApiKey;
+        // Use timing-safe comparison to prevent timing attacks
+        if (token.length !== this.config.adminApiKey.length)
+            return false;
+        return timingSafeEqual(Buffer.from(token, 'utf-8'), Buffer.from(this.config.adminApiKey, 'utf-8'));
     }
     /** Rate limit check / 速率限制檢查 */
     checkRateLimit(ip) {
@@ -691,6 +844,27 @@ export class ThreatCloudServer {
         entry.count++;
         return entry.count <= this.config.rateLimitPerMinute;
     }
+    /**
+     * Parse JSON body and validate against a Zod schema.
+     * Returns validated data or null (sends 400 on failure).
+     */
+    async parseAndValidate(req, res, schema) {
+        const body = await this.readBody(req);
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            this.sendJson(res, 400, { ok: false, error: 'Invalid JSON body' });
+            return null;
+        }
+        const result = tryValidateInput(schema, raw);
+        if (!result.ok) {
+            this.sendJson(res, 400, { ok: false, error: result.error });
+            return null;
+        }
+        return result.data;
+    }
     /** Read request body with size limit / 讀取請求主體（含大小限制） */
     readBody(req) {
         return new Promise((resolve, reject) => {