A goal-based AI agent for identifying critical vulnerability chains in enterprise networks
Vulnerability Finder is an intelligent cybersecurity tool that discovers the most dangerous attack paths through enterprise networks using A search algorithm*. It analyzes Exploit-Dependency Graphs (EDGs) to identify critical vulnerability chains and recommends optimal mitigation strategies.
Key Features:
- 🔍 Intelligent Path Discovery – Uses A* algorithm with CVSS-based heuristics to find optimal attack paths
- 🌐 Real-time CVE Integration – Fetches live vulnerability data from the NVD (National Vulnerability Database)
- 🎯 Multi-Mode Analysis – Live mode for custom networks or pre-built sample scenarios
- 📊 Comprehensive Reporting – Generates visual attack paths and mitigation recommendations
- ✅ Test Coverage – Extensive unit tests for core algorithms
The agent models an enterprise network as a directed AND/OR attack graph where:
- Nodes represent vulnerabilities (CVEs) or network states
- Edges represent access gained by exploiting vulnerabilities
- A Search* finds the minimum-cost path from external entry point → target core asset
| Component | Definition |
|---|---|
| g(n) | Cumulative cost to reach node n (actual exploit difficulty) |
| h(n) | Estimated remaining cost (CVSS exploitability score) |
| f(n) | Total estimated path cost |
This ensures the algorithm finds the fastest attack path while being computationally efficient.
- Python 3.8 or higher
- pip (Python package manager)
# Clone the repository
git clone https://github.com/Sujaicodes/Vulnerability_Finder
cd Vulnerability_Finder
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # macOS/Linux
# OR
venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txtnetworkx– Graph operations and algorithmsrequests– HTTP requests for NVD APIcolorama– Terminal color outputbeautifulsoup4– HTML parsing (for NVD data)
python main.pyThe tool presents two operational modes:
- Enter custom CVEs and network topology manually
- Fetches real-time vulnerability data from NIST NVD API
- Analyzes your specific attack surface
- Best for: Testing specific networks or threat scenarios
- Pre-built enterprise scenarios with known vulnerability chains
- Available scenarios:
- Enterprise network – Log4Shell vulnerability exploitation chain
- Web application stack – Spring4Shell vulnerability exploitation chain
- No external API calls required
- Best for: Learning, demos, and testing
$ python main.py
┌─────────────────────────────────────────────────────────┐
│ VULNERABILITY FINDER: Attack Graph Explorer │
└─────────────────────────────────────────────────────────┘
Choose mode:
1. Live (enter custom CVEs)
2. Sample scenarios
> 2
Select a scenario:
1. Enterprise network (Log4Shell chain)
2. Web application stack (Spring4Shell chain)
> 1
[Running A* search: EXTERNAL → CORE_ASSET]
✓ Critical path found! Total attacker cost: 3.2
[Attack Path Visualization and Recommendations]Run the full test suite to validate core components:
# Run all tests with verbose output
pytest tests/ -v
# Run specific test file
pytest tests/test_astar.py -v
# Run with coverage report
pytest tests/ --cov=src| Module | Tests |
|---|---|
| A Search* | Pathfinding, admissibility verification |
| Graph Builder | Node/edge creation, AND/OR logic |
| Heuristic | CVSS calculation, admissibility |
| Graph Analysis | Connectivity, vulnerabilities |
Vulnerability_Finder/
├── main.py # Entry point
├── requirements.txt # Project dependencies
├── README.md # This file
├── LICENSE # MIT License
│
├── src/
│ ├── core/ # Core algorithms
│ │ ├── astar.py # A* search implementation
│ │ ├── graph_builder.py # Build attack graphs
│ │ ├── heuristic.py # CVSS-based heuristic
│ │ └── path_analyzer.py # Path analysis & recommendations
│ │
│ ├── models/ # Data structures
│ │ ├── network.py # Network topology model
│ │ ├── vulnerability.py # Vulnerability model
│ │ └── attack_graph.py # Attack graph model
│ │
│ ├── utils/ # Utilities
│ │ ├── cvss_calculator.py # CVSS score computation
│ │ ├── logger.py # Logging/formatting
│ │ ├── nvd_client.py # NVD API client
│ │ └── visualizer.py # Output formatting
│ │
│ └── demo/ # Demo & UI
│ ├── demo_runner.py # Interactive demos
│ └── sample_networks.py # Pre-built scenarios
│
├── tests/ # Unit tests
│ ├── test_astar.py # A* algorithm tests
│ ├── test_graph_builder.py # Graph building tests
│ ├── test_heuristic.py # Heuristic validation
│ └── test_admissibility.py # Admissibility checks
│
└── data/ # Sample data
├── sample_topology.json # Network topology
├── sample_vulnerabilities.json # Vulnerability data
└── scenarios/
├── enterprise_network.json # Enterprise scenario
└── web_app_stack.json # Web app scenario
- Optimal pathfinding algorithm for attack graphs
- Guarantees shortest cost path when heuristic is admissible
- Handles AND/OR nodes for complex attack scenarios
- Constructs attack graphs from vulnerability data
- Models attack dependencies and preconditions
- Supports dynamic edge creation
- Computes CVSS-based admissible heuristics
- Ensures A* optimality
- Highly efficient for large graphs
- Analyzes critical attack paths
- Generates mitigation recommendations
- Ranks vulnerabilities by impact
- Vulnerability – CVE information, CVSS scores, descriptions
- Network – Node topology, asset definitions
- AttackGraph – Multi-node structures with attack semantics
from src.core.graph_builder import build_attack_graph
from src.core.astar import astar_search
from src.core.path_analyzer import recommend_mitigation
# Build attack graph
G = build_attack_graph(nodes, edges)
# Find optimal attack path
path = astar_search(G, start="EXTERNAL", goal="CORE_ASSET")
# Get mitigation recommendations
if path:
recommendations = recommend_mitigation(G, path)
for rec in recommendations:
print(f"Patch: {rec['cve']} (Impact: {rec['impact']})")graph = AttackGraph()
graph.add_node(node_id, cvss_score=7.5, cve="CVE-2021-44228")
graph.add_edge(source, target, dependency_type="OR")vuln = Vulnerability(
cve_id="CVE-2021-44228",
cvss_score=10.0,
description="Log4j RCE",
exploitability=3.9
)The tool uses the NIST NVD API for real-time CVE data. Visit nvd.nist.gov for API documentation.
Add new attack scenarios in data/scenarios/ as JSON files:
{
"nodes": [
{"id": "EXTERNAL", "type": "entry_point"},
{"id": "CVE-2021-44228", "type": "vulnerability", "cvss": 10.0}
],
"edges": [
{"source": "EXTERNAL", "target": "CVE-2021-44228"}
]
}Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Add tests for new functionality
- Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Maintain test coverage above 80%
- Follow PEP 8 style guidelines
- Document new functions with docstrings
- Update README for significant changes
- Graph Size: Efficiently handles networks with 500+ nodes
- Search Time: Typically <1s for moderate networks due to A* pruning
- Memory: Linear scaling with graph size
- NVD API: Cached queries to minimize API rate limiting
- AND/OR graph evaluation requires exponential worst-case time
- NVD API has rate limits (~5 requests/30 seconds)
- Heuristic quality depends on CVSS data accuracy
# Verify internet connection and NVD API status
curl https://services.nvd.nist.gov/rest/json/cves/1.0- Ensure all dependencies installed:
pip install -r requirements.txt - Clear Python cache:
find . -type d -name __pycache__ -exec rm -r {} +
- Reduce graph size in sample data
- Consider breaking analysis into smaller subgraphs
- A Algorithm*: Hart, P. E., Nilsson, N. J., & Raphael, B. (1968). "A Formal Basis for the Heuristic Determination of Minimum Cost Paths"
- CVSS (Common Vulnerability Scoring System): https://www.first.org/cvss/
- NVD (National Vulnerability Database): https://nvd.nist.gov/
- NetworkX: https://networkx.org/
This project is licensed under the MIT License – see LICENSE file for details.
For issues, questions, or suggestions:
- 📧 Open an Issue
- 💬 Start a Discussion
Made with ❤️ for cybersecurity research and defense