CodexAegis is an advanced, high-contrast interactive DevSecOps dashboard and chaos core vulnerability simulation tool. It is designed to model autonomous multi-agent pipelines scanning reposit[...]
Crafted with a distinct Neo-Brutalist aesthetic, CodexAegis utilizes:
- Heavy solid black borders (
border-4 border-black) - High-contrast color blocks (deep warning oranges, security emeralds, cyber yellows, and rich off-whites)
- Distinctive 3D offset drop shadows (
shadow-[8px_8px_0px_0px_#1A1A1A]) - Fully fluid and optimized layouts tailored for great readability across both standard desktop monitors and mobile ports
- View active system node connections representing critical files and endpoints (e.g., Auth Server, Payment Gateway, Cookie Manager).
- Dynamically monitor live status variables (Secure, Under Attack, Compromised, or Patched) marked by distinct color states.
- Click any node to instantly view its localized status summary and security telemetry.
- Dual Pipeline Modalities: Switch effortlessly between the Autonomous Single-Agent Core and the Isolated Multi-Agent Pipeline.
- Execution Pipelines: Observe dedicated autonomous agents (
Aegis-Scanner,Aegis-Breacher,Aegis-Synthesizer, andAegis-Certifier) executing sequential scanning and patching.
- Real-time simulated execution streams of security tests displayed inside eye-safe, customized terminal shells.
- Supports logs for active breaches, parameters trace analyses, code validation evaluations, and branch creation histories.
- Inline comparisons showing original insecure statements alongside recommended parameterized remediations.
- Automated generation of Git Branch pull request details (branch metadata, structured titles, and granular diagnostic Markdown descriptions).
- Granular review, approval, and independent rollbacks for individual vulnerability fixes itemized block-by-block.
- Promotes total engineering trust through non-destructive, staging-level validation reviews.
- Framework: React 18 + Vite with TypeScript for clean, reliable, type-safe operations.
- Styling: Tailwind CSS for fluid mobile-first layouts, flexible flexboxes, custom scrollbars, and aesthetic padding.
- Micro-Animations: Framer Motion (via
motion/react) driving key pipeline movements, state transitions, and responsive triggers. - Vector Assets: Lucide React for precise developer-focused iconography.
- Node.js (v16 or higher)
- npm or yarn package manager
- Google Gemini API Key (required for AI-powered simulations)
-
Clone the repository
git clone https://github.com/radmm/CodexAegis.git cd CodexAegis -
Install dependencies
npm install # or yarn install -
Configure environment variables
- Copy
.env.exampleto.env.localcp .env.example .env.local
- Add your Google Gemini API key to
.env.local:GEMINI_API_KEY=your_actual_gemini_api_key_here APP_URL=http://localhost:3000
- Copy
-
Start the development server
npm run dev # or yarn devThe application will be available at
http://localhost:3000 -
Build for production
npm run build # or yarn build -
Start the production server
npm start # or yarn start
npm run dev- Start development server with hot reloadnpm run build- Build for production (Vite + esbuild)npm start- Run production servernpm run clean- Remove build artifactsnpm run lint- Run TypeScript type checking
Follow these steps to operate the simulation:
- Specify any remote pipeline directory path using the interactive Repository Path input bar.
- Choose a targeted vulnerability archetype using the Threat Exploit Selector dropdown menu:
- SQL Injection (
auth-servicelogin bypass vulnerabilities) - Bypass Checkout API Limit (race conditions in order processing endpoints)
- HttpOnly Cookie Missing Flag (unsafe session credential handling)
- SQL Injection (
- Single-Agent Security Cycle: Runs a comprehensive end-to-end automated compromise run to produce a combined remediation patch.
- Atomic Repairs Pipeline: Breaks down found issues sequentially. Runs localized sandboxes for each CVE and prompts developer-driven git branch merges and rollbacks.
- Press the Initiate Security Cycle or Dispatch Atomic Repairs button situated in the footer action block.
- Monitor the step-by-step agent transition and log generation inside the simulated sandboxed terminal.
- Copy recommended code modifications directly with a single click using the Copy Remediation buttons.
- View auto-formatted, ready-to-use branch commands or export complete mock JSON stats directly into your local buffers.
- Never commit
.env.localor any files containing API keys to version control. The.gitignoreshould include.env.local. - Always use environment variables or secrets management systems (e.g., GitHub Secrets, cloud provider secret managers) for sensitive credentials.
- Rotate your Gemini API keys regularly and monitor API usage for unauthorized access.
- In production, the server listens on
0.0.0.0:3000. Consider restricting this to specific IP ranges or running behind a reverse proxy (nginx, Apache) for additional security. - Set
NODE_ENV=productionin production environments to disable Vite dev server middleware.
- Repository URL inputs are passed to the AI model—ensure proper validation to prevent prompt injection attacks.
- All user inputs should be sanitized before being sent to external APIs (Gemini).
- Configure CORS policies appropriately if the frontend and backend are on different domains.
- Use HTTPS in production to encrypt API communications with the Gemini service.
- Keep dependencies updated:
npm auditandnpm updateregularly. - Review the audit report for vulnerabilities:
npm audit --productionto focus on production dependencies. - The project uses
@google/genai,express, andreactas key dependencies—monitor their security advisories.
- The application demonstrates insecure cookie handling as a teaching tool. In production systems:
- Always set
httpOnly: trueto prevent XSS attacks - Always set
secure: truefor HTTPS-only transmission - Use
sameSite: 'strict'or'lax'for CSRF protection
- Always set