Metadata-Version: 2.4
Name: aivas
Version: 0.1.0
Summary: AI-Assisted Network Vulnerability Assessment System — offline CVE scanning, bilingual risk narration, Textual TUI
Author: Michael Megewa
Author-email: Baraka Malila <bmalila87@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Baraka-Malila/aivas
Project-URL: Repository, https://github.com/Baraka-Malila/aivas
Keywords: security,vulnerability,nmap,cve,network,cli,swahili
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: requests>=2.31
Requires-Dist: python-nmap>=0.7
Requires-Dist: groq>=0.9
Requires-Dist: ollama>=0.2
Requires-Dist: jinja2>=3.1
Requires-Dist: weasyprint>=60.0
Requires-Dist: packaging>=23.0
Requires-Dist: paramiko>=3.0
Requires-Dist: pywinrm>=0.4.3
Requires-Dist: nvdlib>=0.7
Requires-Dist: textual>=0.80
Requires-Dist: pyyaml>=6.0
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: PyJWT>=2.8
Requires-Dist: bcrypt>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: responses>=0.25; extra == "dev"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0; extra == "notebook"
Requires-Dist: pandas>=2.0; extra == "notebook"
Requires-Dist: matplotlib>=3.7; extra == "notebook"
Requires-Dist: seaborn>=0.13; extra == "notebook"
Dynamic: license-file

# AIVAS

**AI-Assisted Network Vulnerability Assessment System**

AIVAS is a free, offline-capable network vulnerability scanner for Linux. It combines Nmap service discovery, a local NIST NVD CVE database, active configuration probing, and optional AI-powered bilingual (English/Swahili) risk narration.

![AIVAS TUI](docs/assets/screenshot.png)

---

## Features

- CVE correlation against a local SQLite database synced from NIST NVD (200,000+ CVEs)
- CISA KEV flagging — marks CVEs actively exploited in the wild
- Level 1 active configuration probing: missing security headers, exposed endpoints, risky HTTP methods
- AI risk narration in English and Swahili via Groq or Ollama
- Interactive Textual TUI with slash commands and AI-routed free text input
- Scan history, HTML/PDF report export, and diff between scan sessions
- Fully offline after initial database sync

---

## Requirements

- Linux (Ubuntu 20.04+, Kali, Debian)
- Python 3.10 or later
- nmap (`sudo apt install nmap`)
- pip 23 or later

---

## Installation

```bash
pip install aivas
```

If `aivas` is not found after install, add the local bin directory to your PATH:

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### Install from source

```bash
git clone https://github.com/Baraka-Malila/aivas.git
cd aivas
python3 -m pip install --upgrade pip
python3 -m pip install -e ".[dev]"
```

---

## Quick Start

```bash
# Check your setup
aivas doctor

# Populate the CVE database (from local NVD JSON feeds)
aivas update-db --source /path/to/nvd-json-data-feeds/

# Or sync from the NVD API
aivas update-db

# Sync known exploited vulnerabilities
aivas update-kev

# Launch the interactive interface
aivas
```

---

## Usage

### Interactive TUI

Run `aivas` with no arguments to open the interface. Type `/help` for a full command list.

| Command | Description |
|---------|-------------|
| `/scan <target>` | Full CVE and config probe scan |
| `/quick <target>` | Fast service scan (level 1) |
| `/deep <target> [--udp]` | Full scan with UDP discovery |
| `/ask <query>` | Natural language scan routing (requires API key) |
| `/doctor` | Check dependencies and configuration |
| `/history list` | View past scan sessions |
| `/history show <id>` | Replay findings from a previous scan |
| `/kev` | Sync CISA Known Exploited Vulnerabilities |
| `/config set <key> <value>` | Save a configuration value |
| `/help` | List all commands |
| `/exit` | Quit |

Free text without a leading `/` is routed to the AI intent parser if an API key is configured. Without an API key, all core scanning features work without AI.

### Command line

```bash
aivas scan 192.168.1.1
aivas scan 192.168.1.1 --level 2 --save --report report.html
aivas scan 192.168.1.1 --narrate --api-key YOUR_KEY
sudo aivas scan 192.168.1.1 --udp
aivas search apache --version 2.4.52
aivas history list
aivas config set api_key YOUR_GROQ_KEY
```

---

## Scan Levels

| Level | What it does |
|-------|-------------|
| 1 | Service version detection only |
| 2 | CVE correlation + NSE vulnerability scripts + config probing (default) |
| 3 | Level 2 + SSH-authenticated installed package scan |

---

## Configuration

Settings are stored in `~/.aivas/config.yml`:

```yaml
api_key: your-groq-api-key
provider: groq        # groq or ollama
lang: both            # en, sw, or both
default_level: 2
```

Set any value:

```bash
aivas config set provider ollama
aivas config show
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and how to submit changes.

---

## License

MIT. See [LICENSE](LICENSE).

AIVAS is intended for use on networks you own or have explicit authorisation to scan. Unauthorised scanning may be illegal in your jurisdiction.

---

## Authors

Baraka Malila and Michael Chacha Megewa  
Diploma in Computer Engineering, MUST (Mbeya University of Science and Technology), 2025/2026  
Supervisor: Namsembwa Mzava
