Porcupine is an incredibly advanced, zero-config Web Application Firewall (WAF) and Runtime Application Self-Protection (RASP) engine. It provides a stunning, interactive terminal dashboard to monitor live production traffic, block external attacks (SQLi, XSS), and intercept internal threats from compromised dependencies.

🌟 Core Features

• Live Hacker Dashboard: A 12x12 interactive terminal grid featuring real-time ASCII line charts, pie charts, HTTP method distributions, and scrolling traffic tables.
• Advanced WAF: Automatically intercepts and blocks SQL Injection, Cross-Site Scripting (XSS), Path Traversal, and Command Injection.
• Deep RASP Engine (Supply Chain Defense): Hooks deeply into Node.js at runtime. Freezes Object.prototype, and blocks malicious NPM packages from spawning reverse shells (child_process.exec) or stealing .env files (fs.readFileSync).
• Remote Telemetry Uplink: Stream live attack data securely from a deployed AWS/Vercel production server straight to your local CLI.
• SMTP Attack Alerts: Automatically dispatches a critical email alert directly to your security team the moment an attack is intercepted.
• CSV Audit Export: Export live proxy logs directly to your OS Downloads folder with a single keystroke.
• Universal Cloud Compatibility: Works natively on Express.js, Next.js, Vercel Edge, Netlify, AWS, and more!

📦 Installation

Install globally to use the CLI dashboard as a standalone tool:

npm install -g porcupine-waf

Install locally to protect a specific project in production:

npm install porcupine-waf

💻 1. CLI Command Center (Local & Remote Monitoring)

Porcupine features a framework-agnostic HTTP reverse proxy CLI. It doesn't matter if you are running React, Angular, Next.js, or a Python server—Porcupine protects them all.

🛡️ Protect a Local Project

Wrap an invisible WAF shield around any local project and monitor traffic interactively.

porcupine monitor http://localhost:3000

(Your app is now securely proxied and protected on port 5000!)

📡 Live Remote Uplink (Production Monitoring)

Connect to a remote, deployed production server (running on AWS, GCP, Vercel) and stream the live security traffic straight to your local terminal dashboard!

porcupine live https://my-live-website.com -k your-secret-admin-key

⌨️ Interactive Dashboard Shortcuts

Once the dashboard is running, use these hotkeys to perform operations:

• [s] or [/]: Search Engine - Type a URL or IP to instantly filter the traffic log.
• [f]: Threat Isolation - Instantly filter the dashboard to only show BLOCKED attacks.
• [a]: Safe Mode - Filter the dashboard to only show ALLOWED traffic.
• [d]: Audit Export - Instantly download all traffic logs as a .csv file straight to your Downloads folder.
• [m]: Mail Setup - Opens an interactive prompt to configure SMTP credentials for automated attack alerts.
• [c]: Clear - Reset all filters and search queries.
• [Up/Down]: Scroll - Interactively scroll through the live traffic tables.
• [q] or [ESC]: Quit - Shut down the dashboard safely.

☁️ 2. Production Integration (Cloud & Serverless)

Porcupine is designed to be deployed. By integrating the middleware into your code, you activate the internal RASP immune system.

A. Next.js / Serverless Edge (Vercel, Netlify)

Porcupine ships with a native Universal Adapter for Web API Request/Response environments. Just drop it into your Next.js middleware.js:

import { NextResponse } from 'next/server';
import { nextjsProtector } from 'porcupine-waf';

// 1. Initialize the WAF with SMTP Alert settings!
const protect = nextjsProtector({
  smtp: {
    host: 'smtp.gmail.com', port: 587,
    user: process.env.SMTP_USER, pass: process.env.SMTP_PASS,
    dest: '[email protected]'
  }
});

export function middleware(req) {
  // 2. Run the WAF check at the Edge
  const blockResponse = protect(req);
  if (blockResponse) return blockResponse; // Traffic was malicious! Blocked & Email Sent!
  
  // 3. Traffic is safe, continue routing
  return NextResponse.next();
}

B. Node.js / Express.js (AWS, GCP, DigitalOcean)

For traditional long-running servers, Porcupine acts as standard middleware while simultaneously exposing a hidden secure Server-Sent Events (SSE) telemetry stream.

import express from 'express';
import { porcupineProtector } from 'porcupine-waf';

const app = express();

// Activate Porcupine Protection, Remote Telemetry, & Email Alerts!
app.use(porcupineProtector({
  secretKey: 'your-secret-admin-key',
  smtp: {
    host: 'smtp.gmail.com', port: 587,
    user: process.env.SMTP_USER, pass: process.env.SMTP_PASS,
    dest: '[email protected]'
  }
}));

app.get('/', (req, res) => res.send('Protected App'));
app.listen(8080);

🧠 How RASP Works (Runtime Application Self-Protection)

The moment porcupineProtector() or nextjsProtector() is executed in your environment, Porcupine patches the global Node.js runtime:

1. Anti-Prototype Pollution: Object.prototype is completely frozen.
2. Anti-Reverse Shell: Native child_process.exec is intercepted. If an installed NPM package secretly tries to run commands like wget, nc, or bash -i, Porcupine intercepts it, blocks the command, and throws a massive red warning into the logs.
3. Sensitive File Lockdown: Native fs.readFileSync is monitored. If a rogue package attempts to read /etc/passwd or ~/.aws/credentials, the thread is instantly terminated.

🤝 Contributing

We welcome contributions from the community!

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingSecurityPatch).
3. Commit your changes (git commit -m 'Add some AmazingSecurityPatch').
4. Push to the branch (git push origin feature/AmazingSecurityPatch).
5. Open a Pull Request.

📜 License

Distributed under the MIT License. See LICENSE for more information.

"Stop attacks from the outside, and neutralize threats from the inside."