Methodology & Approach

The project followed an iterative secure-engineering methodology: specify a threat-informed pipeline first, implement modules against that design (Flask API, security layer, LLM client, validator, SSH executor, RAG pipeline, formatting and logging), then validate behavior in a controlled multi-host lab. Each stage in the live system mirrors a documented responsibility—from authenticated POST /api/execute orchestration through optional AI explanations of reports and scripts.

Primary execution paths are (1) built-in safe modes for script archive and managed cron, or (2) standard flow: host context probe (OS, services, listening sockets per host), optional RAG retrieval of trusted examples, OpenAI-compatible chat generation with output cleanup, command validation and normalization, parallel SSH execution with automatic archival of multi-line scripts, and response formatting with optional second-pass natural-language explanation.

For the step-by-step operator view of the pipeline, see the Interactive Workflow; for module-level detail, see the ShellSentry system documentation in the repository.

Technology Stack

Backend

  • Python, Flask, Flask-Login, Flask-SQLAlchemy
  • Paramiko SSH and parallel execution helpers
  • Validation, RAG (sentence-transformers + FAISS), and logging modules

Frontend

  • Jinja templates, HTML, CSS, and vanilla JavaScript
  • Dashboard UI for summaries, AI explanations, and expandable technical reports
  • Responsive layout and actionable error surfacing