EVA - Moses Yebei

Abstract

EVA is an AI-assisted penetration testing agent that enhances offensive security workflows by providing structured attack guidance, contextual analysis, and multi-backend AI integration.

The Problem

EVA addresses a gap in offensive security workflows: pentesters often switch between multiple AI backends, run repetitive recon commands, and manually correlate outputs to decide next steps. The tool wraps AI-driven attack guidance around a pentest shell so a user can execute commands, have the output analyzed in context, and get suggested follow-ups without leaving the terminal.

What This Does

EVA is a Python CLI that guides penetration tests through reconnaissance, exploitation, and reporting phases. It supports multiple AI backends (Ollama, OpenAI, Anthropic, Gemini, custom endpoints) via modules/llm.py, and persists session state—targets, chat history, model context—through sessions/eva_session.py. The modules/ folder handles the operational pieces: attack_map.py builds network graphs, exploit_search.py queries exploit databases, reporting.py generates findings, and tooling.py validates shell commands before execution.

The repo is a fork of ARCANGEL0/EVA (518 stars) with 18 Python files across modules/, utils/, and sessions/. It has no tests, no CI, no license file, and no lockfile—hygiene issues that matter for anyone planning to modify or redistribute it.

How It Is Wired

Execution starts in eva.py at cli (line 166), which reaches 180 functions and is the sole entry point. From there, control flows through main (line 53) into the interactive menu. The shortest path to an external effect is cli -> open_in_default_editor (via subprocess.run) and main -> menu (via os.system), so a single run can spawn subprocesses within two hops.

The busiest hub is utils/ui.py's cyber function, called from 18 places—it handles command execution and output display. utils/system.py (35 functions) and modules/llm.py (34 functions) are the other heavy hitters, both touching files, subprocesses, and the network. modules/llm.py also calls a model for inference. sessions/eva_session.py is the most unstable module (instability 0.83), importing 10 modules and sitting at the edge of the graph.

Two modules—utils/ui.py and utils/system.py—are in a circular import cycle, which makes changes ripple unpredictably. Deep nesting (max depth 8) in llm.py, eva_session.py, and system.py compounds the cognitive load.

How To Use It

git clone https://github.com/moses-y/EVA
cd EVA
pip install -e .  # from pyproject.toml
python eva.py      # entry point: cli() at eva.py:166

Configuration lives in config.py and utils/config_loader.py; the README documents backend selection (Ollama, OpenAI, Anthropic, Gemini, custom API) but does not specify exact environment variable names. Sessions persist under sessions/. The repo lacks a lockfile, so builds are not reproducible without committing one.

Real-World Use

A consultant running an external engagement could use EVA to automate recon: define a target, let the AI suggest nmap and enum4linux commands, execute them inside the shell, and have outputs analyzed for vulnerabilities. The session file preserves context across days, and modules/reporting.py can generate a findings report at the end.

Code Health & Issues

Static analysis (not opinion) found 15 issues: 5 high, 10 medium. The high-severity items are:

Import cycle – utils/ui.py, utils/system.py are mutually reachable; break the cycle by extracting shared types.
Deep nesting – max depth 8 in modules/llm.py, sessions/eva_session.py, utils/system.py; flatten with guard clauses.
Duplicated code – 16 repeated 6-line blocks across 16 files; extract shared helpers.

Medium findings include broad except clauses in utils/ui.py and modules/llm.py, unmanaged open() calls in modules/attack_map.py and modules/reporting.py, oversized files (exploit_search.py at 765 lines), and high branching density in modules/tooling.py and modules/vuln_intel.py.

SDLC gaps: no test suite, no CI pipeline, no license file (default is all-rights-reserved, blocking reuse), and no lockfile for reproducible builds.

The Bottom Line

EVA is a functional prototype with real utility for guided pentesting, but it is not production-grade. The circular imports and missing test coverage make it risky to modify without breaking behavior. Use it for internal experimentation or as a reference for building your own AI-assisted shell—but add a license, tests, and CI before treating it as a deliverable.

What the analyser found

Deployment readiness

2/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

24 files

Python18
Markdown1
TOML1

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["modules<br/>9 modules"] g1["utils<br/>4 modules"] g2["(root)<br/>3 modules"] g3["sessions<br/>2 modules"] g3 -->|6| g0 g2 -->|3| g1 g0 -->|3| g1 g3 -->|3| g1 g0 -->|2| g2 g2 -->|1| g0 g2 -->|1| g3 g3 -->|1| g2 g1 -->|1| g2

Module dependencies

The 10 most depended-upon modules of 18, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_utils_ui["ui"] n1_config["config"] n2_utils_config_loader["config_loader"] n3_utils_system["system"] n4_modules_tooling["tooling"] n5_sessions_eva_session["eva_session"] n6_modules_exploit_search["exploit_search"] n7_modules_llm["llm"] n8_modules_workflow["workflow"] n9_modules_attack_map["attack_map"] n6_modules_exploit_search --> n2_utils_config_loader n6_modules_exploit_search --> n1_config n6_modules_exploit_search --> n4_modules_tooling n6_modules_exploit_search --> n0_utils_ui n7_modules_llm --> n2_utils_config_loader n7_modules_llm --> n1_config n5_sessions_eva_session --> n2_utils_config_loader n5_sessions_eva_session --> n1_config n5_sessions_eva_session --> n9_modules_attack_map n5_sessions_eva_session --> n6_modules_exploit_search n5_sessions_eva_session --> n7_modules_llm n5_sessions_eva_session --> n4_modules_tooling n5_sessions_eva_session --> n8_modules_workflow n5_sessions_eva_session --> n3_utils_system n5_sessions_eva_session --> n0_utils_ui n3_utils_system --> n2_utils_config_loader n3_utils_system --> n1_config n3_utils_system --> n0_utils_ui classDef cyc stroke:#ef4444,stroke-width:2px; class n0_utils_ui,n3_utils_system cyc;

Findings

MediumNo test files detected - untested code paths repository-wide
MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config
MediumNo LICENSE file - unclear usage/redistribution rights root
LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium1

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Add a test suite; this repository has nonehigh18 occurrences

18 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Add a workflow that builds and tests this repositoryhigh

18 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.