SOC Grader

AI-powered security case quality scoring with intelligent investigation questions

SOC Grader is a web application that evaluates the quality and completeness of security case documentation using AI-powered analysis. It generates investigation questions based on security alerts and scores how well cases address those questions.

Quick Start

Pre-requisites: Node.js 18+ and npm (or yarn/pnpm) - Download and install from https://nodejs.org/en/download

1. Clone the repository:

   git clone <repository-url>
   cd SOCGrader

2. Install and Start application:

   npm install
   npm start

   This command automatically starts both the frontend development server and the proxy server.

3. Open your browser: Navigate to http://localhost:5173

That's it! The application is now running.

Environment variables

Create a .env file in the project root (see .env.example). The app works with defaults for local development.

Variable	Required	Description
SERVER_HOST	No	Host for the proxy server (default: localhost)
SERVER_PORT	No	Port for the proxy server (default: 3001)
FRONTEND_PROXY_URL	No	URL the frontend uses to call the proxy (default: http://localhost:3001)
SERVER_BASE_PATH	No	Base path for server routes, e.g. /socgrader-backend (default: empty)
FRONTEND_ORIGIN	No	Allowed CORS origin for the frontend (default: http://localhost:5173)
TRUST_PROXY	No	Set to true when behind a TLS-terminating reverse proxy (production)
FORCE_HTTPS	No	Set to true in production to redirect HTTP to HTTPS
ENABLE_RATE_LIMITING	No	Set to true in production to rate-limit sign-in and log endpoints
SESSION_TTL_MINUTES	No	Session expiry in minutes (default: 1440 = 24h). Only applies when sign-in is configured.

The frontend receives the proxy URL at build time via FRONTEND_PROXY_URL (Vite injects it as VITE_FRONTEND_PROXY_URL).

Note: Sign-in does not work in a local setup. Use the Configure tab with your own API credentials to run analysis.

Security and production deployment

• HTTPS: Do not expose the app directly over HTTP to the internet. In production, run the Node server behind a TLS-terminating reverse proxy (e.g. nginx, Cloudflare, or your host’s load balancer). Set TRUST_PROXY=true and optionally FORCE_HTTPS=true so the app redirects HTTP to HTTPS.
• CORS: The server allows only the origin set by FRONTEND_ORIGIN (default http://localhost:5173). Set this to your frontend’s public URL in production (e.g. https://your-app.example.com).
• Rate limiting: Set ENABLE_RATE_LIMITING=true in production to limit sign-in and client-log requests per IP.
• Sessions: When sign-in is configured, sessions expire after SESSION_TTL_MINUTES (default 24 hours) and are cleaned up periodically.

Usage

1. Configure API Credentials:

   • Go to the "Configure" tab
   • Select your AI provider (OpenAI, Claude, or Gemini)
   • Choose a model
   • Enter your API key
   • Click "Save Credentials"

2. Set Scoring Guidelines (Optional):

   • Go to the "Guidelines" tab
   • Add guidelines for question generation
   • Adjust scoring weights for different answer labels

3. Analyze a Case:

   • Go to the "Score" tab
   • Enter the security alert details
   • Enter the security case documentation
   • Click "Analyze"
   • Review the score, summary, and detailed evaluation

License

This project is licensed under the MIT License — see the LICENSE file for details.

Powered by

AirMDR - 24×7 AI-Powered MDR