praxis-sec 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Praxis contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# Praxis
+
+<p align="center">
+  <img src="assets/praxis-logo.svg" alt="Praxis Logo" width="620">
+</p>
+
+<p align="center">
+  <a href="https://github.com/Ganron007/Praxis/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Ganron007/Praxis/ci.yml?label=CI" alt="CI"></a>
+  <a href="https://github.com/marketplace/actions/praxis-sec-scan"><img src="https://img.shields.io/badge/Marketplace-Praxis%20Security%20Scan-blue" alt="GitHub Marketplace"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/Node.js-%E2%89%A518.0.0-blue.svg" alt="Node.js: >=18.0.0">
+  <img src="https://img.shields.io/npm/v/praxis-sec?label=Version" alt="npm version">
+  <img src="https://img.shields.io/badge/Status-Public%20Beta-yellow.svg" alt="Status: Public Beta">
+</p>
+
+**Praxis is an AI Security Testing (AIST) CLI — an AI-native scanner with a working fix loop.** 28 parallel agents assess the entire AI/agent attack surface — LLM apps, agents, MCP servers, RAG pipelines, model files, datasets, eval harnesses — plus a baseline of secrets and code vulnerabilities. An LLM drafts fixes you approve, applies, verifies, and can undo. Offline by default. No registration, no data leaves your machine.
+
+> [!IMPORTANT]
+> **Local & gated by design.** Core scans run entirely offline. LLM remediation is
+> opt-in, drafts diffs for your approval, writes atomically, and logs every change
+> for undo.
+
+---
+
+## What it does
+
+| Capability | In one line |
+| --- | --- |
+| **AI/agent surface audit** | 28 concurrent agents: prompt injection, MCP tool abuse, agent-memory poisoning, pickle-based model files, RAG, agent session telemetry, local agent-abuse (EAA), and AI infrastructure inventory (gateways, runtimes, API endpoints) |
+| **AST & Taint Dataflow** | Pure ESM AST & CST parsing (JS/TS & Python) with lexical scope trees, intra-file taint tracking, source-to-sink data flow, and guardrail detection |
+| **Dynamic AI Red Teaming** | DAST fuzzing engine for live LLM endpoints and agent runtimes (`praxis redteam`) with customizable attack probes and evasion benchmarks |
+| **Find → fix → verify** | LLM drafts a diff → you approve → atomic apply → tiered verification ladder (AST syntax → build → tests → re-scan) with auto-revert of failed fixes → undo log |
+| **Governance audits** | Detects *missing* controls: no human-oversight gates, no observability wiring — EU AI Act Art. 14 / 12 evidence |
+| **MCP trust registry & live probing** | Known MCP servers with trust scores (SHA-256 integrity-checked) + live runtime JSON-RPC handshakes and tool fuzzing (`--test-live`) |
+| **Threat intel** | 7 core sources cached locally — 6 remote feeds (OSV, GHSA, KEV, EPSS, NVD, Gitleaks) plus the bundled AI threatpack — and 5 optional keyed providers (Snyk, Socket, Phylum, Sonatype, GitGuardian); findings enriched with exploit likelihood |
+| **Compliance mapping** | Findings tagged against 8 frameworks — OWASP LLM/ML/Agentic, MITRE ATLAS (+ mitigations & case studies), NIST AI 600-1, AVID, EU AI Act, ISO 42001, Google SAIF |
+| **Professional HTML report** | Tabbed single-file report: overview KPIs + severity distribution, OWASP ASI agentic-risk coverage, per-agent coverage, findings with rule IDs and AST taint blocks, standards matrix, Agent BOM, remediation plan, remediation ledger (incl. declines and reasons), score trend, and a provenance footer |
+| **Web UI** | `praxis web` — register projects, run scans, watch live progress, browse findings. Read-only, loopback-only by default |
+| **Portable rules** | `praxis rules export` — 411 pattern rules as Semgrep-compatible YAML, with a manifest that states plainly what Praxis does that Semgrep cannot |
+| **CI-native** | `scan ci` gates, SARIF for Code Scanning with real `security-severity` ranking, net-new PR gating (fails only on *introduced* findings), GitHub Action inline PR annotations |
+| **Reproducible** | Every scan reports a provenance fingerprint (tool, runtime, probe/threatpack/data versions), and CI enforces determinism between two runs |
+
+## Quick start
+
+```bash
+npm install && npm link
+
+praxis scan .            # full 28-agent audit + AST taint evaluation
+praxis fix .             # interactive LLM-guided fixes
+praxis redteam .         # dynamic AI red team & DAST prober
+praxis agents audit .    # audit the AI/agent surface
+praxis agents mcp --test-live  # live MCP JSON-RPC probe
+praxis web               # local web UI for scans and findings
+praxis report benchmark  # run ground-truth accuracy benchmark
+praxis rules export      # portable Semgrep-compatible rule bundle
+praxis intel update      # refresh local threat feeds
+praxis vibe .            # emoji-graded A–F score
+```
+
+`praxis --help` lists everything. Run `praxis` with no args for the interactive REPL.
+
+## How it works
+
+<p align="center">
+  <img src="assets/praxis-architecture.svg" alt="Praxis Architecture" width="100%">
+</p>
+
+## Command groups
+
+```
+praxis scan       secrets · full · changed · env · redteam · standard · ci
+praxis fix        interactive · quick · from-report · rotate · undo · env-template
+praxis agents     audit · skill · mcp · bom · serve (MCP server)
+praxis intel      update · deps · advisories
+praxis report     team · legal · checklist · sbom · benchmark
+praxis project    init · doctor · hooks · guard · watch · baseline · plugins · policy
+praxis rules      list · export · import      (portable rule bundles)
+praxis web        local web UI                (read-only, loopback by default)
+
+praxis vibe       emoji-graded A–F score
+praxis score      numeric score
+```
+
+## 28 agents at a glance
+
+| Cluster | Agents | Covers |
+| --- | --- | --- |
+| AI / LLM security | 13 | Prompt injection, MCP, agentic AI, RAG, memory poisoning, model files, agent configs, agent telemetry & abuse (EAA), AI infra inventory |
+| Code vulnerabilities | 4 | Injection, SSRF, XSS, ReDoS, exception handling, vibe-coding anti-patterns |
+| Auth & API | 3 | JWT flaws, CSRF, IDOR/BOLA, Supabase RLS, unauthenticated routes |
+| Supply chain | 3 | Typosquatting, malicious scripts, agent attestation, CI permissions |
+| Config & platform | 5 | Docker, K8s, Terraform, CORS/CSP, mobile, CICD, git history, PII |
+
+Full agent list and rule IDs: **[docs/USAGE.md](docs/USAGE.md)**.
+
+## LLM configuration
+
+Optional, for `--deep` analysis, `redteam`, and `fix interactive`. Put a `.env` in your working
+directory — any OpenAI-compatible gateway works:
+
+```bash
+OPENAI_API_KEY=sk-...
+OPENAI_BASE_URL=https://your-gateway.example/v1/chat/completions
+PRAXIS_LLM_MODEL=your-model
+PRAXIS_LLM_REASONING=high   # low | medium | high
+```
+
+Template: [`.env.example`](.env.example) · Verify with `praxis project doctor`.
+
+## CI
+
+```yaml
+- uses: Ganron007/Praxis@master
+  with:
+    threshold: '80'
+    net-new: 'true'        # fail only on findings introduced by the PR
+    fail-on-new: 'high'
+    always-fail-on: 'critical'
+    sarif: 'true'          # upload to GitHub Code Scanning
+```
+
+For `sarif: true`, grant the job permission to upload to Code Scanning:
+
+```yaml
+permissions:
+  security-events: write
+```
+
+`net-new: true` scans the PR's base ref in a worktree and fails only on findings the PR
+*introduced*, so an inherited backlog never blocks a merge.
+
+## Portable rules
+
+Praxis rules are portable data, not lock-in:
+
+```bash
+praxis rules list                    # rule inventory by source, severity, portability
+praxis rules export -o ./rules       # Semgrep YAML + canonical JSON + portability manifest
+semgrep --config ./rules/praxis-rules.yaml .
+```
+
+The export covers the **411 pattern rules**. The accompanying
+`praxis-rules.manifest.json` states plainly what Praxis does that Semgrep cannot express —
+AST/taint dataflow, the prompt-injection probe corpus, entropy-checked secrets, and LLM deep
+analysis — rather than implying full coverage. Import round-trips through the JSON:
+
+```bash
+praxis rules import ./rules/praxis-rules.json --write-plugin .praxis/agents
+```
+
+Rules that cannot be executed as static patterns are rejected **with a reason**, never
+imported in a degraded form.
+
+## Documentation
+
+| Document | Content |
+| --- | --- |
+| [docs/USAGE.md](docs/USAGE.md) | Complete command & flag reference |
+| [docs/THREAT_INTEL.md](docs/THREAT_INTEL.md) | Feed architecture & schemas |
+| [docs/THIRD_PARTY_NOTICES.md](docs/THIRD_PARTY_NOTICES.md) | Vendored data attribution |
+| [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md) | Contributing & agent authoring |
+| [.github/SECURITY.md](.github/SECURITY.md) | Reporting vulnerabilities |
+
+## Scope & limitations
+
+Praxis is an **AI-security-first** scanner combining pattern recognition, pure ESM AST & CST parsing, intra-file taint analysis, dynamic endpoint probing, and LLM verification. While significantly minimizing false positives and mapping dataflow from user input to hazardous sinks, standards mapping reports controls with evidence rather than formal compliance certification. Review fixes before applying them to production.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Praxis contributors.

package/ai-defense/cost-protection.md

@@ -0,0 +1,292 @@
+# AI Cost Protection Guide
+
+**Prevent your AI features from bankrupting you.**
+
+Real incidents: $50k+ bills from runaway AI usage, abuse, or misconfiguration.
+
+---
+
+## Why Cost Protection Matters
+
+| Scenario | Risk |
+|----------|------|
+| Leaked API key | Anyone can rack up charges on your account |
+| No rate limits | Single user sends 10,000 requests |
+| Long responses | GPT-4 response = $0.03-0.12 per request |
+| Infinite loops | Code bug calls AI repeatedly |
+| Viral launch | 10x traffic = 10x costs |
+
+---
+
+## Layer 1: API Key Security
+
+### Keep keys server-side only
+
+```typescript
+// BAD: Key in frontend code
+const openai = new OpenAI({ apiKey: 'sk-...' });
+
+// GOOD: Key in server environment variable
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+```
+
+### Scan for leaked keys
+
+```bash
+npx praxis-sec scan .
+```
+
+### Rotate keys periodically
+
+- OpenAI: Dashboard > API Keys > Create new > Delete old
+- Anthropic: Console > API Keys > Rotate
+
+---
+
+## Layer 2: Request Limits
+
+### Token limits per request
+
+```typescript
+// Limit input
+const MAX_INPUT_CHARS = 2000;
+if (userInput.length > MAX_INPUT_CHARS) {
+  return "Message too long";
+}
+
+// Limit output
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: messages,
+  max_tokens: 500,  // Hard cap on response length
+});
+```
+
+### Rate limiting per user
+
+```typescript
+import { Ratelimit } from '@upstash/ratelimit';
+
+const aiRatelimit = new Ratelimit({
+  redis,
+  limiter: Ratelimit.slidingWindow(10, '1 m'),  // 10 requests/minute
+});
+
+async function aiHandler(request, userId) {
+  const { success } = await aiRatelimit.limit(userId);
+  if (!success) {
+    return new Response('Too many requests', { status: 429 });
+  }
+  // Process request
+}
+```
+
+### Global rate limiting
+
+```typescript
+const globalRatelimit = new Ratelimit({
+  redis,
+  limiter: Ratelimit.slidingWindow(1000, '1 h'),  // 1000 requests/hour total
+  prefix: 'ratelimit:global:ai',
+});
+```
+
+---
+
+## Layer 3: Budget Caps
+
+### Track usage in database
+
+```typescript
+interface AIUsageRecord {
+  userId: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cost: number;
+  timestamp: Date;
+}
+
+async function logUsage(usage: AIUsageRecord) {
+  await db.aiUsage.create({ data: usage });
+}
+```
+
+### Calculate cost before request
+
+```typescript
+// Approximate cost calculation
+const COSTS = {
+  'gpt-4': { input: 0.03 / 1000, output: 0.06 / 1000 },
+  'gpt-4-turbo': { input: 0.01 / 1000, output: 0.03 / 1000 },
+  'gpt-3.5-turbo': { input: 0.0005 / 1000, output: 0.0015 / 1000 },
+  'claude-3-opus': { input: 0.015 / 1000, output: 0.075 / 1000 },
+  'claude-3-sonnet': { input: 0.003 / 1000, output: 0.015 / 1000 },
+};
+
+function estimateCost(model: string, inputTokens: number, maxOutputTokens: number) {
+  const rates = COSTS[model] || COSTS['gpt-4'];
+  return (inputTokens * rates.input) + (maxOutputTokens * rates.output);
+}
+```
+
+### Enforce user budget
+
+```typescript
+async function checkUserBudget(userId: string, estimatedCost: number) {
+  const dailyLimit = 1.00;  // $1/day per user
+  const monthlyLimit = 10.00;  // $10/month per user
+
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+
+  const dailyUsage = await db.aiUsage.aggregate({
+    where: { userId, timestamp: { gte: today } },
+    _sum: { cost: true },
+  });
+
+  if ((dailyUsage._sum.cost || 0) + estimatedCost > dailyLimit) {
+    throw new Error('Daily AI budget exceeded');
+  }
+
+  // Similar check for monthly
+}
+```
+
+### Global budget circuit breaker
+
+```typescript
+async function checkGlobalBudget(estimatedCost: number) {
+  const monthlyBudget = 500.00;  // $500/month total
+
+  const monthStart = new Date();
+  monthStart.setDate(1);
+  monthStart.setHours(0, 0, 0, 0);
+
+  const monthlyUsage = await db.aiUsage.aggregate({
+    where: { timestamp: { gte: monthStart } },
+    _sum: { cost: true },
+  });
+
+  if ((monthlyUsage._sum.cost || 0) + estimatedCost > monthlyBudget) {
+    // CIRCUIT BREAKER: Disable AI features
+    await disableAIFeatures();
+    await alertAdmins('AI budget exceeded - features disabled');
+    throw new Error('Service temporarily unavailable');
+  }
+}
+```
+
+---
+
+## Layer 4: Provider-Side Limits
+
+### OpenAI usage limits
+
+1. Go to platform.openai.com
+2. Settings > Limits
+3. Set monthly hard limit
+
+### Anthropic usage limits
+
+1. Go to console.anthropic.com
+2. Settings > Usage Limits
+3. Set spend limits
+
+### Set up billing alerts
+
+Most providers support alerts at:
+- 50% of budget
+- 80% of budget
+- 100% of budget
+
+---
+
+## Layer 5: Monitoring & Alerts
+
+### Real-time usage dashboard
+
+```typescript
+// Track key metrics
+const metrics = {
+  requestsPerMinute: await getRequestsPerMinute(),
+  costToday: await getCostToday(),
+  costThisMonth: await getCostThisMonth(),
+  topUsers: await getTopUsersByUsage(),
+  errorRate: await getErrorRate(),
+};
+```
+
+### Alert on anomalies
+
+```typescript
+async function checkForAnomalies() {
+  // Alert if hourly cost exceeds normal
+  const hourlyCost = await getHourlyCost();
+  const avgHourlyCost = await getAvgHourlyCost();
+
+  if (hourlyCost > avgHourlyCost * 3) {
+    await sendAlert({
+      type: 'anomaly',
+      message: `Hourly AI cost spike: $${hourlyCost} (avg: $${avgHourlyCost})`,
+      severity: 'high',
+    });
+  }
+
+  // Alert if single user is abusing
+  const topUser = await getTopUserThisHour();
+  if (topUser.requests > 100) {
+    await sendAlert({
+      type: 'abuse',
+      message: `User ${topUser.id} made ${topUser.requests} AI requests this hour`,
+      severity: 'medium',
+    });
+  }
+}
+```
+
+---
+
+## Cost Comparison: Models
+
+| Model | Input ($/1M tokens) | Output ($/1M tokens) | Best For |
+|-------|---------------------|----------------------|----------|
+| GPT-4 | $30 | $60 | Complex tasks |
+| GPT-4 Turbo | $10 | $30 | Long context |
+| GPT-3.5 Turbo | $0.50 | $1.50 | Simple tasks |
+| Claude 3 Opus | $15 | $75 | Highest quality |
+| Claude 3 Sonnet | $3 | $15 | Balanced |
+| Claude 3 Haiku | $0.25 | $1.25 | Speed/cost |
+
+**Tip:** Use cheaper models for simple tasks, reserve expensive models for complex ones.
+
+```typescript
+function selectModel(task: string) {
+  const simpleTasks = ['summarize', 'classify', 'extract'];
+  const complexTasks = ['code', 'analyze', 'create'];
+
+  if (simpleTasks.some(t => task.includes(t))) {
+    return 'gpt-3.5-turbo';  // Cheap and fast
+  }
+  return 'gpt-4-turbo';  // Better but pricier
+}
+```
+
+---
+
+## Quick Implementation Checklist
+
+1. [ ] API keys in server-side environment variables only
+2. [ ] Input length limits (e.g., 2000 chars)
+3. [ ] Output token limits (e.g., 500 tokens)
+4. [ ] Rate limiting per user (e.g., 10 requests/minute)
+5. [ ] Daily budget per user (e.g., $1/day)
+6. [ ] Global monthly budget with circuit breaker
+7. [ ] Provider-side hard limits configured
+8. [ ] Billing alerts at 50%, 80%, 100%
+9. [ ] Usage tracking in database
+10. [ ] Anomaly detection and alerting
+
+---
+
+**Remember: A $50,000 surprise bill is a real risk. Implement these layers before launch.**