Architecture Overview

NetOpsForge is a Windows-first network automation platform built for Cisco environments.

Core Components

netopsforge/
  cli.py              # CLI entrypoint (argparse) — all subcommands
  runner.py           # Pack execution engine
  governance.py       # Policy-as-code enforcement
  credentials.py      # Windows Credential Manager integration
  platform_mapping.py # Schema platform → Netmiko device_type mapping
  error_translator.py # Friendly error messages for common failures
  mode.py             # Operating mode (autocor/general)
  doctor.py           # Environment health checker
  onboarding.py       # Interactive first-run setup wizard
  learning.py         # Just-in-time learning modules
  explain.py          # Glossary lookup with network analogies
  metrics.py          # Progress tracking (SQLite-backed dashboard)
  starter_packs.py    # Starter template selection and generation
  credential_wizard.py# Credential add/list interactive wizard
  pack_diff.py        # Pack version comparison and changelog generation
  pack_graph.py       # Dependency graph with topological sort (DAG)
  pack_linter.py      # Style, security, and best-practice linting
  rbac.py             # Role-based access control engine
  __main__.py         # python -m netopsforge entrypoint
  integrations/
    sqlite_integration.py   # Execution history database
    rest_api_client.py      # REST API client (ACI, Meraki, ISE, etc.)
    netconf_client.py       # NETCONF transport (ncclient)
    restconf_client.py      # RESTCONF transport (HTTPS/YANG)

Execution Flow

CLI parses arguments and invokes the runner
Runner loads pack YAML and validates against JSON Schema
Governance engine checks commands against policy rules
RBAC engine checks caller permissions against rbac.yml (graceful skip if absent)
Credentials are retrieved from Windows Credential Manager
Platform mapping translates schema platform to connection type
Commands execute via Netmiko SSH (CLI), REST API (HTTPS), NETCONF, or RESTCONF
Validation rules check output for errors/patterns
Results are logged to SQLite and file-based logs

Pack System

Packs are YAML files that define automation tasks:

Schema: schemas/pack.schema.json (JSON Schema draft-07)
Template: packs/_TEMPLATE.yml (annotated reference)
Examples: packs/examples/ (production-ready, CI-validated)
Starters: packs/starters/ (copy-and-customize templates)

Packs can declare dependencies on other packs using metadata.depends_on. The graph command builds a DAG from these declarations and computes safe execution order.

Supported Platforms

Platform	Connection	Transport
Cisco IOS XE	SSH via Netmiko	`cisco_ios`
Cisco IOS XE (NETCONF)	NETCONF via ncclient	`netconf_client`
Cisco IOS XE (RESTCONF)	RESTCONF via HTTPS	`restconf_client`
Cisco ACI	REST API via HTTPS	`rest_api_client`
Cisco Meraki	REST API via HTTPS	`rest_api_client`
Cisco Catalyst Center	REST API via HTTPS	`rest_api_client`
Cisco SD-WAN	REST API via HTTPS	`rest_api_client`
Cisco ISE	REST API via HTTPS	`rest_api_client`
Webex	REST API via HTTPS	`rest_api_client`

CLI Commands

Command	Purpose
`run <pack>`	Execute a pack against a device
`validate <pack>`	Validate pack schema and governance rules
`diff <old> <new>`	Compare two pack versions; `--changelog` for markdown output
`lint <path>`	Check pack for style, security, and best-practice issues
`graph [dir]`	Show pack dependency tree; `--validate` checks for cycles; `--order` prints execution order
`doctor`	Check environment health (Python, Git, credentials, schema)
`credential add/list`	Manage device credentials in Windows Credential Manager
`onboard`	Interactive setup wizard for first-time users
`learn [topic]`	Just-in-time learning modules (git-basics, yaml-syntax, credentials, etc.)
`starter [template]`	Create a pack from a starter template
`explain [term]`	Glossary lookup with network analogies
`metrics dashboard/stats`	View progress dashboard and event statistics

Quality & Safety Tools

Pack Linter (`pack_linter.py`)

Checks pack YAML for: - Style issues (missing tags, long descriptions, non-semantic versioning) - Security issues (hardcoded IPs or credentials, verify_ssl: false in production) - Best-practice issues (missing validation rules, no save_to_file for write packs) - Missing fields that are optional but recommended

Run: py -m netopsforge lint packs/my-pack.yml

Pack Diff (`pack_diff.py`)

Compares two pack versions field-by-field and reports added, removed, and changed fields. The --changelog flag generates a Markdown-formatted changelog suitable for PR descriptions.

Run: py -m netopsforge diff packs/v1.yml packs/v2.yml --changelog

Pack Dependency Graph (`pack_graph.py`)

Builds a directed acyclic graph (DAG) from metadata.depends_on declarations across all packs in a directory. Supports: - Cycle detection (--validate) - Topological execution order (--order) - Tree visualization (default output)

Run: py -m netopsforge graph packs/ --validate

Access Control (RBAC)

rbac.py implements a role-based access control engine that gates pack execution. Configuration lives in rbac.yml at the repo root (optional — omitting the file skips RBAC checks for backward compatibility).

When present, rbac.yml defines roles and permissions. The runner checks the caller's role before executing or dry-running a pack and raises an error if access is denied.

Governance

Policy rules in policies/rules.yml define:

Read patterns: Commands allowed without a ticket
Write patterns: Commands requiring a change ticket (ABC-123 format)
Blocked patterns: Commands never allowed (e.g., write erase, reload)

CI/CD Pipeline

GitHub Actions runs on every PR:

Pack validation against schema
Python tests (3.11 and 3.12)
Windows tests
Security scanning (Bandit, safety)
Documentation build (MkDocs strict)
GitHub Pages deployment on merge to main