🛡️

PCIRS NetDevOps Engine

v4.1 FINAL
FINAL PROJECT · NETWORK AUTOMATION · AI-ENHANCED

PCIRS NetDevOps Engine

An advanced, AI-enhanced network automation platform that prevents configuration drift and catastrophic outages through a 4-layer validation pipeline — combining rule-based syntax checking, boundary validation, context-aware state machines, and local LLM-powered delta risk scoring before any configuration reaches production hardware.

7
Python Modules
4
PCIRS Filters
5
Vendor OSes
10×
Parallel SSH
~2K
Lines of Code

Project Objectives

// What PCIRS Engine was built to solve

01

Eliminate Configuration Drift

Provide a digital twin editing environment so engineers work on an isolated copy, never touching real hardware until fully validated.

02

Multi-Layer Validation Pipeline

Enforce 4 sequential validation gates — syntax, range, state machine, AI delta — catching error categories no single tool addresses.

03

AI-Assisted Risk Scoring

Use a local LLM (Phi-3 Mini via LM Studio) to evaluate intent and network-impact risk of proposed changes, not just syntax correctness.

04

Multi-Vendor Support

Support 5 vendor OS families (Cisco IOS, Huawei VRP, Arista EOS, HP Comware, Aruba OS) with vendor-specific validation rules.

05

Zero-Trust Deployment

Enforce backend security locks so no configuration can be pushed to hardware without an explicit PCIRS pipeline approval flag.

06

Role-Based Access & Full Audit

Implement 3-tier RBAC, CSV audit logging, and SMTP email alerts to ensure accountability for all network changes.

Problem Statement

// The gap this project fills

⚠ The Problem

  • GAPNetwork CLI errors (typos, wrong mode, out-of-range values) cause outages. Human review is slow and inconsistent.
  • GAPExisting tools like Ansible/NAPALM push configs blindly — no intent validation or AI risk evaluation.
  • GAPMulti-vendor environments create extra risk: Huawei "undo" vs Cisco "no", different VLAN/STP ranges, different mode hierarchies.
  • GAPNo standard tool provides context-aware state machine checking (ensuring commands are in the correct config mode).

✔ The PCIRS Solution

  • SOLDigital twin editing isolates proposed changes from live network hardware entirely.
  • SOL4-filter pipeline catches syntax errors, invalid ranges, mode violations, and network-risk changes before push.
  • SOLLocal Phi-3 Mini LLM evaluates change intent and returns a structured risk verdict (ALLOW / WARN / BLOCK).
  • SOLBackend security lock at deploy_engine.py prevents any bypass of the validation pipeline.

Scope & Deliverables

// What is included in v4.1

DeliverableModuleStatusDescription
4-Filter PCIRS Pipelinepcirs_checker.pyDONESyntax, Ranges, State Machine, AI Delta checks
Streamlit Dashboardapp.pyDONE7-tab UI, RBAC, theme injection, MOTD
Multi-threaded Sync Enginesync_engine.pyDONE10× parallel SSH, 3-format config storage, LLDP topology
Zero-Trust Deploy Enginedeploy_engine.pyDONEICMP+TCP check, backend lock, Netmiko push
Auth & Audit Systemauth_engine.pyDONESHA-256, RBAC, CSV audit log, SMTP alerts
Portal Config Persistenceconfig_engine.pyDONETheme, SMTP, MOTD, custom commands, auto-backup
Quick Risk Pre-Checkrisk_engine.pyDONELocal rules: Mgmt VLAN, trunk shutdown detection
Automated Backup Enginesync_engine.pyDONETimestamped configs/backups/, configurable schedule

System Architecture

// Module roles, dependencies, and data flows

// HUB-SPOKE MODULE ARCHITECTURE

app.py Streamlit Frontend Hub 7 Tabs · RBAC · Session State PCIRS_CHECKER.PY 4-Filter Validation Pipeline run_all_checks(config, device_type) RISK_ENGINE.PY Quick Local Rule Check analyze_risk(config, device) AUTH_ENGINE.PY Users · RBAC · Audit · Email check_login · log_action · send_email CONFIG_ENGINE.PY Portal Settings · Theme · MOTD load_config · save_config · apply_theme SYNC_ENGINE.PY Sync · Monitor · Terminal · Topology sync_network · build_topology · run_terminal DEPLOY_ENGINE.PY Zero-Trust Config Push deploy_to_real(pcirs_verified=True) LM STUDIO [external] Phi-3 Mini · Port :1234 POST /v1/chat · JSON Schema output ← Filter 4 only (via pcirs_checker) NETWORK DEVICES [external] Cisco IOS · Huawei VRP · Arista EOS · HP Comware · Aruba OS SSH via Netmiko + Paramiko · Legacy crypto patch for SG300 user_db.yaml · portal_config.yaml configs/ · audit_log.csv

Module Reference Table

// Each module's role, key functions, and dependencies

ModuleRoleKey FunctionsDepends OnLOC (est.)
app.pyStreamlit frontend hub7 tabs, CSS injector, RBAC gate, session stateAll modules~1277
pcirs_checker.py4-filter validation pipelinecheck_syntax, check_ranges, check_state_machine, check_ai_delta, run_all_checksrequests, difflib~649
sync_engine.pySync, monitor, terminal, topologysync_network, build_topology_map, run_terminal_command, get_device_status, run_automated_backupsnetmiko, paramiko, concurrent.futures~380
deploy_engine.pyZero-trust config pushdeploy_to_real, is_reachable, translate_to_realnetmiko, paramiko, socket~120
auth_engine.pyUser mgmt, auth, audit, emailcheck_login, create_user, log_action, send_email_notification, get_logsconfig_engine, smtplib, hashlib, pandas~150
config_engine.pyPortal settings persistenceload_config, save_config, apply_streamlit_themeyaml, os~60
risk_engine.pyQuick pre-check rule engineanalyze_riskre~40

Data Storage Schema

// File-based persistence layer

user_db.yaml

  • KEYusername (string, unique)
  • FLDpassword (SHA-256 hex digest)
  • FLDemail (string)
  • FLDrole (Super Admin / Admin / Read Only)

real_inventory.yaml

  • KEYhostname (string, unique)
  • FLDip, username, password, type
  • FLDinterface_map {twin: real}

portal_config.yaml

  • UIcompany_name, logo_url, logo_width
  • UItheme_primary/bg/sec_bg/text/btn_text
  • SYSsmtp_*, auto_backup_*, last_backup_run
  • SYScustom_commands {}, motd

configs/ directory

  • .cfgDigital twin config (interface names translated)
  • _orig_original.cfg — raw device config verbatim
  • .jsonStructured config tree (context → [commands])
  • BCKbackups/Hostname_YYYY-MM-DD_HH-MM-SS.cfg

audit_log.csv

  • COLTimestamp (YYYY-MM-DD HH:MM:SS)
  • COLUser · Action · Details
  • COLAuthorized By (Super Admin username)
  • NOTESorted newest-first; downloadable via UI

.streamlit/config.toml

  • AUTOAuto-generated by apply_streamlit_theme()
  • FLDprimaryColor, backgroundColor
  • FLDsecondaryBackgroundColor, textColor

System Flowcharts

// Three architectural diagrams — click to switch

01 · Full Process Flow
02 · Services Interaction
03 · AI Model Flow (Filter 4)

// FULL PROCESS FLOW — End-to-End User Journey

USER — Login Request auth_engine.py SHA-256 verify · RBAC role assign app.py — DASHBOARD 7-Tab Streamlit UI · MOTD · Dynamic CSS Theme SYNC DEVICE CONFIGS sync_engine · 10× parallel SSH · .cfg + _original.cfg + .json EDIT DIGITAL TWIN Config Manager · Twin ↔ Real interface mapping RUN PCIRS AUDIT PIPELINE pcirs_checker.py · 4 sequential filters · run_all_checks() FILTER 1: SYNTAX Typo · Abbrev Wrong Negation · Unknown FILTER 2: RANGES IP · VLAN · STP · BGP Subnet Masks · OSPF · HSRP FILTER 3: STATE Mode Stack Tracking Global → Interface → VLAN FILTER 4: AI DELTA difflib + LM Studio Phi-3 Mini · JSON Schema AGGREGATE RESULTS run_all_checks() returns · safe_to_push flag set safe_to_push? YES NO BLOCKED Errors shown to user AUTHORIZE Super Admin 2FA required deploy_engine.py ICMP ping + TCP :22 check Netmiko SSH · send_config_set + save_config AUDIT LOG WRITTEN CSV · Timestamp · User · Action · Authorizer 📧 SMTP Email Alert → Super Admins

// SERVICES INTERACTION — Data Flow Between Modules

app.py Streamlit Frontend 7 Tabs · RBAC · Session PCIRS_CHECKER 4-Filter Pipeline run_all_checks(config, dtype) RISK_ENGINE Local rule pre-check analyze_risk() AUTH_ENGINE Users · RBAC · Audit check_login · log_action CONFIG_ENGINE Portal settings persist load_config · save_config SYNC_ENGINE Sync · Terminal · Topology 10× parallel SSH sessions DEPLOY_ENGINE Zero-trust config push ICMP+TCP+Netmiko LM STUDIO [ext] Phi-3 Mini · :1234 POST /v1/chat (F4 only) NETWORK DEVICES [ext] Cisco · Huawei · Arista · Comware · Aruba SSH via Netmiko + Paramiko run_all_checks() analyze_risk() check_login · log_action sync_network · terminal deploy_to_real(pcirs_verified) POST /v1/chat (Filter 4 only)

// AI DELTA FLOW — Filter 4 LM Studio Integration

RUNNING CONFIG Device's live current config configs/Device_original.cfg PROPOSED CONFIG User-edited digital twin configs/Device.cfg difflib.unified_diff() Generate unified diff locally · No LLM cost yet Any diff? NO DIFF SHORT CIRCUIT Return GREEN · Skip LLM DIFF EXISTS BUILD LLM REQUEST System prompt: expert network engineer role Attach diff delta · Enforce JSON schema · max_tokens: 1000 POST → LM Studio :1234 model: phi-3-mini · response_format: json_schema Local LAN inference — no cloud API, no data leaves network PARSE JSON RESPONSE overall_risk · overall_action · safe_to_push changes_detected[] · warnings[] · blocking_reasons[] ✔ ALLOW · safe_to_push = true (GREEN) ⚠ WARN · safe_to_push = true (YELLOW) ⛔ BLOCK · safe_to_push = false (RED)

Project Timeline

// Development phases and milestones — 10-week plan

GANTT CHART — Development Phases

W1
W2
W3
W4
W5
W6
W7
W8
W9
W10
Requirements & Design
Architecture
auth_engine.py
Auth + RBAC
config_engine.py
Config Persist
sync_engine.py
Sync + LLDP + Terminal
deploy_engine.py
Zero-trust Deploy
risk_engine.py
Risk Rules
pcirs_checker F1+F2
Syntax + Ranges
pcirs_checker F3
State Machine
pcirs_checker F4 (AI)
LM Studio Integration
app.py — Dashboard
Streamlit Frontend
Multi-threaded Sync
ThreadPoolExecutor
Automated Backups
Backup Engine
Testing & Refinement
QA + Fixes
Documentation
README + Comments

Development Milestones

WeekMilestoneDeliverableStatus
W1–W2System Design & RequirementsArchitecture diagram, module plan, inventory schemaDONE
W2–W3Foundation Modulesauth_engine.py + config_engine.py working, user login functionalDONE
W3–W5Network Sync Enginesync_engine.py: SSH pull, LLDP, topology, web terminalDONE
W4–W6Deploy Enginedeploy_engine.py: zero-trust lock, ICMP+TCP, Netmiko pushDONE
W4–W7PCIRS Filters 1–3Syntax, ranges, state machine — all 5 vendors implementedDONE
W6–W8PCIRS Filter 4 (AI)difflib delta + LM Studio JSON schema integrationDONE
W5–W9Streamlit Frontendapp.py: 7 tabs, RBAC gating, CSS theme, MOTD, chartsDONE
W7–W9Performance UpgradesThreadPoolExecutor (sync + monitor), automated backup engineDONE
W9–W10Testing & Bug FixesMulti-vendor testing, edge case hardening, legacy crypto patchDONE
W10v4.1 Final ReleaseREADME, code cleanup, viva preparationDONE

Metrics & Charts

// Project statistics, complexity analysis, and tech breakdown

📄
~2,676
Total Lines of Code
🔍
30+
Validation Rules
⚡
10×
Parallel SSH Sessions
🤖
1
Local LLM Integration

MODULE CODE DISTRIBUTION

PCIRS FILTER COVERAGE AREAS

TECH STACK BREAKDOWN

VALIDATION RULE DISTRIBUTION BY FILTER

Filter 1 — Syntax (5 error types × 5 vendors)25 rules
Filter 2 — Ranges (IP, VLAN, STP, BGP, OSPF, HSRP)20 rules
Filter 3 — State Machine (mode stack × vendor)30 states
Filter 4 — AI (6 structured output fields)AI-driven
Vendor OS Support5 vendors
RBAC Role Coverage3 roles
Config Storage Formats3 formats

SECURITY LAYERS OVERVIEW

Layer 1
SHA-256 Auth
Password hashing + RBAC role assignment at login
Layer 2
UI-Level RBAC
Tab visibility + action availability gated by role
Layer 3
PCIRS Pipeline
4-filter validation before any deployment is permitted
Layer 4
Backend Deploy Lock
pcirs_verified flag enforced at Python function level
Layer 5
Audit Trail
CSV log + SMTP email for all deployment actions

Special Features Checklist

// 35 easily-forgotten implementation details — tick off as you review

FILTER 1 — SYNTAX ENGINE

  • 5 error types: TYPO, ABBREVIATION, AMBIGUOUS, WRONG_NEGATION, UNKNOWN
  • Wrong negation: "undo" on Cisco → WRONG_NEGATION; "no" on Huawei → WRONG_NEGATION
  • Vendor-specific keyword dictionaries for all 5 supported vendors
  • Abbreviation detection: partial commands like "conf t" or "int fa0" caught

FILTER 2 — RANGE VALIDATION

  • IP rejects: network addr, broadcast, loopback (127.x), multicast (224-239), reserved (240+)
  • CIDR notation (e.g., /24) rejected — must use dotted-decimal subnet mask
  • Subnet mask contiguity check — non-contiguous masks like 255.0.255.0 rejected
  • STP priority must be multiple of 4096 (0,4096…61440); Aruba uses 0–15 scale
  • BGP AS 23456 (trans-AS) and 65535 (reserved) explicitly blocked
  • VLAN reserved ranges enforced per vendor (e.g., 1002–1005 on Cisco IOS)

FILTER 4 — AI INTEGRATION

  • difflib short-circuit: empty diff → returns GREEN immediately, LLM never called
  • JSON schema enforcement — LLM cannot hallucinate or return freeform text
  • Output fields: overall_risk (GREEN/YELLOW/RED), overall_action (ALLOW/WARN/BLOCK), safe_to_push bool
  • Local inference: Phi-3 Mini via LM Studio on LAN port :1234 — no cloud API

DEPLOY ENGINE — SECURITY

  • Backend lock: pcirs_verified=True OR is_backup_restore=True required — Python function level
  • Two-step connectivity: ICMP ping (L3) + TCP socket :22 (L4) before SSH attempt
  • send_config_set() + save_config() used — NOT raw send_command()
  • Interface translation: twin names → real names via translate_to_real() before push
  • Checks device output for "% Invalid" or "% Incomplete" even after push succeeds

SYNC ENGINE — DETAILS

  • terminal datadump sent to cisco_ios before show running-config to prevent paging
  • Configs saved in 3 formats: .cfg (twin), _original.cfg (raw), .json (structured tree)
  • LLDP smart parser: detects SG300 format (Port first) vs IOS format (Device ID first)
  • Topology deduplication: sorted tuples prevent A→B + B→A duplicate edges
  • Backup filename: configs/backups/Hostname_YYYY-MM-DD_HH-MM-SS.cfg
  • Legacy crypto patch at module load for Cisco SG300 (in BOTH sync_engine and deploy_engine)

AUTH & CONFIG ENGINE

  • Root "admin" account: username and role are locked even in the full edit form
  • Audit log sorted newest-first, downloadable as CSV, role-gated download button
  • SMTP simulation mode: when smtp_enabled=False, emails print to console (not sent)
  • Backward-compatible config loading: missing YAML keys get default values at runtime
  • MOTD stored in portal_config.yaml, displayed on the login/dashboard screen
  • Admin-defined custom diagnostic buttons appear in Monitoring tab for all users
  • Fail-proof logo handler: gracefully falls back to emoji if image URL fails to load
  • 5-color theme picker: saved to .streamlit/config.toml AND portal_config.yaml

References

// Academic, technical, and library references for the project report

Core Frameworks & Libraries
1
Streamlit Inc. — Streamlit: The fastest way to build data apps

Open-source Python framework used for building the multi-tab web dashboard. Provides reactive UI, session state management, and theme configuration via config.toml.

Frameworkhttps://streamlit.io
2
Kthattin, K. et al. — Netmiko: Multi-vendor library to simplify Paramiko SSH connections to network devices

Core SSH library used in sync_engine.py and deploy_engine.py for device connectivity. Provides send_config_set(), save_config(), and multi-vendor device type abstractions.

Libraryhttps://github.com/kthattin/netmiko
3
Paramiko Contributors — Paramiko: Python SSH2 Implementation

Underlying SSH transport library. Used directly for legacy crypto patching (Transport._preferred_kex, _preferred_ciphers, _preferred_macs) to support older Cisco SG300 hardware.

Libraryhttps://www.paramiko.org
4
Python Software Foundation — difflib: Helpers for computing deltas

Built-in Python library used in Filter 4 to generate unified diffs between running and proposed configurations. Enables the short-circuit optimization (empty diff = skip LLM).

stdlibhttps://docs.python.org/3/library/difflib.html
5
Python Software Foundation — concurrent.futures: High-level interface for async execution

Used in sync_engine.py for ThreadPoolExecutor(max_workers=10) enabling parallel SSH sessions for sync, monitoring, and backup operations.

stdlibhttps://docs.python.org/3/library/concurrent.futures.html
AI & LLM Integration
6
LM Studio — Run LLMs locally with a simple, powerful interface

Local inference server used to host Phi-3 Mini. Provides an OpenAI-compatible REST API on port :1234 with support for structured JSON output via response_format parameter.

AI Toolhttps://lmstudio.ai
7
Microsoft Research — Phi-3 Technical Report: A Highly Capable Language Model Locally on Your Phone (2024)

The 3.8B parameter small language model used for Filter 4 AI Delta analysis. Selected for its ability to run on local hardware while producing high-quality structured outputs for network configuration assessment tasks.

LLMarXiv:2404.14219
8
OpenAI — JSON mode and Structured Outputs in the Chat Completions API

The response_format: json_schema pattern used in Filter 4 is derived from OpenAI's structured outputs specification, which LM Studio implements for local models. This ensures deterministic, schema-compliant LLM responses.

Techniquehttps://platform.openai.com/docs/guides/structured-outputs
Network Standards & Protocols
9
IEEE 802.1D — Spanning Tree Protocol (STP)

Standard referenced in Filter 2 for STP bridge priority validation. Priority must be a multiple of 4096 (0, 4096, 8192, ..., 61440) per the standard's bridge identifier encoding.

StandardIEEE 802.1D-2004
10
IANA — Special-Purpose IPv4 Addresses (RFC 5735 / RFC 1918)

Referenced in Filter 2 IP validation for loopback (127.0.0.0/8), multicast (224.0.0.0/4), and reserved (240.0.0.0/4) address range detection. Also informs network/broadcast address rejection.

RFCRFC 5735, RFC 1918
11
IANA — Autonomous System (AS) Numbers Registry

Referenced in Filter 2 BGP AS validation. AS 23456 (trans-AS) and AS 65535 are reserved and blocked. The valid private AS range (64512–65534) and public range are validated accordingly.

Standardhttps://www.iana.org/assignments/as-numbers
12
IEEE 802.1AB — Link Layer Discovery Protocol (LLDP)

Standard used by the topology crawler in sync_engine.py. The smart parser handles both standard IOS and SG300-specific LLDP neighbor output formats to build the Graphviz topology map.

StandardIEEE 802.1AB-2016
Security & Related Work
13
Huston, G. et al. — SHA-256 (FIPS 180-4: Secure Hash Standard)

Cryptographic hash function used in auth_engine.py for password hashing via Python's hashlib.sha256(). No plain-text passwords are stored anywhere in the system.

SecurityNIST FIPS 180-4
14
National Institute of Standards and Technology — Zero Trust Architecture (NIST SP 800-207)

Conceptual framework underlying the "backend security lock" design in deploy_engine.py. The principle that no actor (even an authenticated user) should be trusted implicitly — all deployments require explicit PCIRS pipeline verification.

FrameworkNIST SP 800-207
15
Related Work
Ansible Network Automation — Cisco IOS Collection

Comparable tool for network automation. PCIRS Engine differentiates itself by adding AI delta risk scoring, state-machine mode validation, and a digital twin architecture rather than direct template-based config push.

Comparisonhttps://docs.ansible.com/ansible/latest/collections/cisco/ios/