Skip to content

README.md

Latest commit

 

History

History
149 lines (102 loc) · 5.01 KB

README.md

File metadata and controls

149 lines (102 loc) · 5.01 KB
Raw

EleVADR - OT Network Security Analysis Tool

Latest Release License: CC0 Python Version React Version Backend Build Frontend Build CodeQL Status pre-commit Open in Dev Containers

EleVADR is a specialized network security analysis engine developed for the Cybersecurity and Infrastructure Security Agency (CISA). It is designed to assess Operational Technology (OT) systems by transforming raw PCAP traffic into actionable security intelligence.

This repository contains both the Python/Zeek backend analysis engine and the React/TypeScript frontend dashboard.

Advanced operational documentation can be found on our GitHub Pages site.

Repository Structure

The repository is structured as a monorepo containing the following primary directories:

  • .devcontainer/: Configuration files for the VS Code Dev Container.
  • .github/: Workflows for CI/CD, binary building, and releases.
  • backend/: Python FastAPI backend, Pandas code, and Zeek scripts.
  • frontend/: React dashboard managed with pnpm and built with Vite.
  • docker-compose.yml: Local multi-service orchestration file.

Running the Complete App

To start both the backend API and the frontend dashboard locally, use the local container orchestration:

docker compose up --build

Once running:

  • Frontend Dashboard: Accessible at http://localhost:8080
  • Backend API: Accessible at http://localhost:8000 (but there is no reason to interact directly)

Development Environment

To avoid local dependency drift, all development should happen inside containers.

1. VS Code Dev Containers (Recommended)

  • Step 1: Open the repository directory in VS Code.
  • Step 2: Click Reopen in Container when prompted.
  • Step 3: If the prompt does not appear, press Ctrl+Shift+P and choose Dev Containers: Rebuild and Reopen in Container.

All necessary tools including zeek, uv, pnpm, and linting utilities are pre-configured inside the environment.

2. Manual Host Setup (Alternative)

If you cannot use Dev Containers, you must manually install Zeek 8.0.5+, Node 22+, and Python 3.14+.

  • Backend Setup:

    cd backend
uv sync

  • Frontend Setup:

    cd frontend
pnpm install

Testing & Quality Assurance

Code Standards

Linting, formatting, and security analysis are run automatically on commit when developing inside the Dev Container. To run these validation checks manually:

pre-commit run --all-files

Running Tests

Test suites are separated by component:

  • Backend Tests:

    cd backend
uv run pytest

  • Frontend Tests:

    cd frontend
pnpm test

Building Docs

Build the documentation locally with:

# First, we need to install the docs dependencies.
uv sync --group docs --directory backend/

# Then, we need to install the backend for the source to be importable
uv pip install -e ./backend

# Finally we can build the docs
sphinx-build -b html docs/source docs/_build/html

# To access them locally, you can just start a server
python -m http.server --directory docs/_build/html 8010

Public Domain

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.