Metadata-Version: 2.1
Name: secure-cartography
Version: 0.9.1
Summary: A secure, Python-based network discovery and mapping tool using SSH-based device interrogation
Home-page: https://github.com/scottpeterman/secure_cartography
Author: Scott Peterman
Author-email: scottpeterman@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Environment :: X11 Applications
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: backports.tarfile>=1.2.0
Requires-Dist: bcrypt>=4.2.1
Requires-Dist: blinker>=1.9.0
Requires-Dist: certifi>=2024.12.14
Requires-Dist: cffi>=1.17.1
Requires-Dist: charset-normalizer>=3.4.0
Requires-Dist: click>=8.1.8
Requires-Dist: colorama>=0.4.6
Requires-Dist: contourpy>=1.3.0
Requires-Dist: cryptography>=44.0.0
Requires-Dist: cycler>=0.12.1
Requires-Dist: docutils>=0.21.2
Requires-Dist: et_xmlfile>=2.0.0
Requires-Dist: Flask>=3.1.0
Requires-Dist: fonttools>=4.55.3
Requires-Dist: func_timeout>=4.3.5
Requires-Dist: future>=1.0.0
Requires-Dist: idna>=3.10
Requires-Dist: igraph>=0.11.8
Requires-Dist: importlib_metadata>=8.5.0
Requires-Dist: importlib_resources>=6.4.5
Requires-Dist: itsdangerous>=2.2.0
Requires-Dist: jaraco.classes>=3.4.0
Requires-Dist: jaraco.context>=6.0.1
Requires-Dist: jaraco.functools>=4.1.0
Requires-Dist: Jinja2>=3.1.5
Requires-Dist: junos-eznc>=2.7.2
Requires-Dist: keyring>=25.5.0
Requires-Dist: kiwisolver>=1.4.7
Requires-Dist: lxml>=5.3.0
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: MarkupSafe>=3.0.2
Requires-Dist: matplotlib>=3.9.4
Requires-Dist: mdurl>=0.1.2
Requires-Dist: more-itertools>=10.5.0
Requires-Dist: n2g>=0.3.3
Requires-Dist: napalm>=5.0.0
Requires-Dist: napalm-procurve>=0.6.0
Requires-Dist: ncclient>=0.6.15
Requires-Dist: netaddr>=1.3.0
Requires-Dist: netmiko>=4.5.0
Requires-Dist: netutils>=1.10.0
Requires-Dist: networkx>=3.2.1
Requires-Dist: nh3>=0.2.20
Requires-Dist: ntc_templates>=7.5.0
Requires-Dist: numpy>=2.0.2
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: packaging>=24.2
Requires-Dist: paramiko>=3.5.0
Requires-Dist: pillow>=11.0.0
Requires-Dist: pkginfo>=1.12.0
Requires-Dist: pycparser>=2.22
Requires-Dist: pyeapi>=1.0.4
Requires-Dist: Pygments>=2.18.0
Requires-Dist: PyNaCl>=1.5.0
Requires-Dist: pynxos>=0.0.5
Requires-Dist: pyparsing>=3.2.0
Requires-Dist: PyQt6>=6.8.0
Requires-Dist: PyQt6-Qt6>=6.8.1
Requires-Dist: PyQt6-WebEngine>=6.8.0
Requires-Dist: PyQt6-WebEngine-Qt6>=6.8.1
Requires-Dist: PyQt6_sip>=13.9.1
Requires-Dist: pyserial>=3.5
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: python-igraph>=0.11.8
Requires-Dist: pywin32-ctypes>=0.2.3
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: readme_renderer>=44.0
Requires-Dist: requests>=2.32.3
Requires-Dist: requests-toolbelt>=1.0.0
Requires-Dist: rfc3986>=2.0.0
Requires-Dist: rich>=13.9.4
Requires-Dist: ruamel.yaml>=0.18.6
Requires-Dist: ruamel.yaml.clib>=0.2.12
Requires-Dist: scp>=0.15.0
Requires-Dist: six>=1.17.0
Requires-Dist: textfsm>=1.1.3
Requires-Dist: texttable>=1.7.0
Requires-Dist: transitions>=0.9.2
Requires-Dist: ttp>=0.9.5
Requires-Dist: ttp-templates>=0.3.7
Requires-Dist: typing_extensions>=4.12.2
Requires-Dist: urllib3>=2.3.0
Requires-Dist: Werkzeug>=3.1.3
Requires-Dist: yamlordereddictloader>=0.4.2
Requires-Dist: zipp>=3.21.0

# Secure Cartography

Secure Cartography is a secure, Python-based network discovery and mapping tool designed for network engineers and IT professionals. It leverages SSH-based device interrogation to automate network discovery, visualize network topologies, and merge network maps across multi-vendor environments.

![Main Application](https://raw.githubusercontent.com/scottpeterman/secure_cartography/refs/heads/main/screenshots/slides.gif)

## Version 0.8.3 Highlights

- **Major Performance Improvements**: 10x faster device discovery and processing
- **Enhanced Visualization**: New interactive Mermaid-based network topology viewer
- **Improved Device Support**: Added support for Aruba/HP ProCurve switches (non-CX)
- **Advanced Logging**: Configurable logging levels with improved output formatting
- **UI Improvements**: 
  - Quick-access buttons for browsing output folders and files
  - Modernized topology merge dialog with interactive preview
  - Enhanced dark/light mode support
- **CLI for automated mapping**:
  - cli args, yaml conf, and env vars for secrets. ver 0.8.1 addresses a hanging bug
  - See Appendix

## Quick Start Guide

1. **Network Discovery and Mapping**
   ```bash
   python -m secure_cartography.scart
   ```

2. **Topology Merge Tool**
   ```bash
   python -m secure_cartography.merge_dialog
   ```

## Key Features
- New improved native map viewer
- Find and Highlight Node on map
- ![Main Application](https://raw.githubusercontent.com/scottpeterman/secure_cartography/refs/heads/main/screenshots/viewer_slides.gif)

### Network Discovery
- Multi-threaded SSH-based device discovery with optimized queue management
- Support for multiple vendor platforms:
  - Cisco IOS
  - Cisco NX-OS
  - Arista EOS
  - Aruba/HP ProCurve (non-CX)
- Improved device tracking and neighbor discovery
- Real-time progress monitoring with enhanced logging
- Smart platform detection and validation
- Configurable exclusion patterns (e.g., `othersite-,sep` to exclude specific sites and IP phones)

### Visualization
- Interactive topology viewer with Mermaid diagrams
- Dark/Light mode theme support
- Multiple export formats:
  - SVG for high-quality graphics
  - GraphML for yEd integration
  - Draw.io compatible format
- Multiple layout algorithms:
  - Kamada-Kawai (KK) for general topologies
  - Circular layout for ring networks
  - Multipartite for layered networks

### Security
- Master password-based encryption system
- Machine-specific keyring integration
 - PBKDF2-based key derivation
- Encrypted credential storage

### Map Merging
- Interactive topology preview
- Intelligent topology merging with connection deduplication
- Comprehensive merge logging
- Multiple file support

## Installation

### From PyPI
```bash
pip install secure-cartography
```

### From GitHub
```bash
git clone https://github.com/scottpeterman/secure_cartography.git
cd secure_cartography
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

### Running the Application
```bash
# Run as installed package
scart
merge-dialog

# Or run as module for additional console output
python -m secure_cartography.scart
python -m secure_cartography.merge_dialog
```

## System Requirements
- Python 3.9+
- PyQt6
- NetworkX
- N2G
- Matplotlib
- Cryptography
- PyYAML
- Paramiko

## System Compatibility

### Tested Environments
- Windows 10 & 11
- Ubuntu 24.04
- Mac OSX (latest as of 12-20-24)
- Python versions 3.9 and 3.12

### Known Issues
- Python 3.13: Compatibility issues with Napalm library

## External Tool Integration

### yEd GraphML (.graphml)
![yEd Example](https://raw.githubusercontent.com/scottpeterman/secure_cartography/refs/heads/main/screenshots/yed1.png)
- Multiple automatic layout algorithms
- Advanced grouping capabilities
- Neighborhood analysis
- High-quality vector export

### draw.io (.drawio)
![draw.io Example](https://raw.githubusercontent.com/scottpeterman/secure_cartography/refs/heads/main/screenshots/drawio.png)
- Collaborative diagram editing
- Web-based access
- Multiple export formats
- Custom stencils and shapes

## Version History

### 0.7.0 (Current)
- 10x performance improvement in device discovery
- Added Aruba/HP ProCurve switch support
- New interactive Mermaid-based topology viewer
- Enhanced logging with configurable levels
- Improved UI with quick-access file management
- Better error handling and recovery

### 0.2.0
- Initial ProCurve support
- Improved device discovery reliability
- Enhanced neighbor discovery
- Added debug logging
- Improved topology mapping
- Better platform detection

## Technology Stack

### Core Technologies
- Python 3.9+
- PyQt6 for GUI
- NetworkX for graph processing
- Matplotlib for visualization
- Cryptography.io for security

### Security Components
- PBKDF2 key derivation
- Fernet encryption
- System keyring integration
- Platform-specific secure storage

### Network Interaction
- Paramiko/SSH2 for device communication
- TextFSM for output parsing
- Custom platform detection
- Enhanced interface normalization

### Data Storage
- JSON for topology data
- YAML for configuration
- SVG for visualizations
- Encrypted credential storage

## Security Architecture

### Credential Protection
1. **Master Password System**
   - PBKDF2-derived key generation
   - Machine-specific salt
   - Secure system keyring integration

2. **Storage Security**
   - Fernet encryption for credentials
   - No plaintext password storage
   - Platform-specific secure storage locations

3. **Runtime Security**
   - Memory-safe credential handling
   - Secure credential cleanup
   - Protected GUI input fields

## Appendix A: CLI Usage

Secure Cartography includes a CLI tool for automation and scripting. The tool can be run as either an installed package or module:

```bash
# Run as installed package
sc --help

# Run as module
python -m secure_cartography.sc --help
```

### Configuration Options

#### YAML Configuration
Create a YAML file with your settings:
```yaml
seed_ip: 172.16.101.1
max_devices: 500
output_dir: "./cli/home"
#username: admin   --- can be here, but its clear text! Please use the environment variable option
#password: pw
verbose: true
map_name: home_network
layout: "rt"  # Optional, defaults to kk
domain: ''    # Optional
exclude: ''   # Optional
timeout: 60   # Optional
```

#### Environment Variables
Set credentials using environment variables:
- `SC_USERNAME`: Primary device username
- `SC_PASSWORD`: Primary device password
- `SC_ALT_USERNAME`: Alternate device username (optional)
- `SC_ALT_PASSWORD`: Alternate device password (optional)

```bash
# Windows
set SC_USERNAME=admin
set SC_PASSWORD=mypass

# Linux/Mac
export SC_USERNAME=admin
export SC_PASSWORD=mypass
```

#### CLI Arguments
```bash
sc --yaml config.yaml --seed-ip 192.168.1.1 --verbose
```

Full argument list:
- `--yaml`: Path to YAML config file
- `--seed-ip`: Starting IP address
- `--username`: Device username
- `--password`: Device password
- `--alt-username`: Alternate username
- `--alt-password`: Alternate password
- `--domain`: Domain name
- `--exclude`: Comma-separated exclude patterns
- `--output-dir`: Output directory path
- `--timeout`: Connection timeout (seconds)
- `--max-devices`: Maximum devices to discover
- `--map-name`: Output map name
- `--layout`: Graph layout algorithm
- `--verbose`: Enable debug logging

### Example Usage

Basic discovery with YAML config:
```bash
sc --yaml network_config.yaml --verbose
```

Full CLI configuration:
```bash
sc --seed-ip 192.168.1.1 --username admin --password secret \
   --output-dir ./maps --max-devices 50 --timeout 60 \
   --map-name office_network --layout kk --verbose
```

Using environment variables:
```bash
export SC_USERNAME=admin
export SC_PASSWORD=secret
sc --yaml config.yaml
```
