Network Automation Lab

A safety-first network validation and automation QA portfolio built around repeatable tests, structured evidence, reviewer-facing interfaces, and explicit execution gates.

Network validation is often demonstrated through one-off terminal sessions, screenshots, and copied output that are difficult to repeat, compare, test, or review. Network Automation Lab treats that work as a small QA platform: local inputs are validated deterministically, results become machine-readable and human-readable evidence, and unsafe or unavailable paths fail closed.

Stage 2: CLOSURE CANDIDATE. Separate Owner-authorized one-shot VRRP read-only proofs completed for MikroTik Lab1 and Lab2, each through the same target-aware fail-closed runtime, one exact command, and zero retries. The Lab2 proof also has independently reviewed persistent startup bindings and fresh-process reconstruction. Final closure still requires independent review and remote Safe CI. Closure candidate scope and evidence.

The August 2026 release baseline is a local Stage-0 product. The supported release path is designed for local portfolio review: mock-only, dry-run, report-only, and display-oriented. Reviewers do not require a router, switch, VPN peer, SSH session, provider account, model API, or private lab configuration. The recorded Stage-2 success grants no new live authority. Stage 3 is NOT STARTED.

Engineering Highlights

• Repeatable validation logic and retained evidence for MikroTik, Cisco, WireGuard, VRRP, and iperf3 scenarios.
• Structured JSON, HTML, and text evidence with bounded reviewer summaries.
• Fail-closed handling for missing, malformed, unavailable, rejected, or blocked evidence.
• A canonical Flask reviewer dashboard plus a secondary Next.js evidence interface.
• Automated regression coverage for parsers, safety boundaries, report projection, CLI behavior, and presentation.
• Explicit separation between report-only, dry-run, mock, historical, and separately gated future capabilities.

Interview / Demo Quick Path

Review in 3 Minutes

Start the canonical local reviewer dashboard:

python dashboard_app.py

Open http://127.0.0.1:5000/ and select Open the 3-minute Stage-0 journey. The walkthrough uses committed Day95 evidence to compare an allowed read-only fake-adapter request with a write-capable request rejected before adapter invocation, connecting the request, safety decision, deterministic evidence, and reviewer conclusion.

This accepted Stage-0 demo path is GET-only. It does not contact devices, invoke provider-backed operations, expose command or job execution controls, change configuration, or demonstrate production approval.

For the recorded Stage-2 result, explain: Lab1 first proved the bounded one-shot chain after two earlier attempts failed closed. Lab2 subsequently completed its own fresh Owner-authorized proof for target.mikrotik.lab02, mikrotik.vrrp_status. The Lab2 authorization was verified and consumed once through replay protection; pinned host trust and a dedicated read-only credential bound the exact command /interface vrrp print detail, which ran once with zero retries and returned normalized evidence. Lab2 did not revalidate Lab1 or establish overall VRRP pair health. This is an evidence discussion, not a live demo procedure.

Other internal or legacy surfaces are outside this interview path. For a documentation-first tour, use the Public Reviewer Walkthrough.

For a no-install preview, view the committed home and reports screenshots. These show reviewer displays, not proof of live-device execution.

Contribute in 15 Minutes

Many beginner-friendly issues are designed to run entirely offline. When an issue is labeled and scoped that way, you can contribute without physical network hardware, credentials, private infrastructure, SSH access, or a cloud or model-provider account.

1. Browse the open good first issue list or the general Issues list.
2. Read CONTRIBUTING.md and the safety guidance in SECURITY.md.
3. Pick one bounded issue whose stated setup and scope fit your environment.
4. Make one focused change and run the issue-specific validation plus the repository-required checks.
5. Open a focused pull request; Safe CI validates the change and a maintainer reviews it.

For implementation-level detail, see the detailed AI-assisted workflow.

The diagram summarizes the intended human-guided flow: local inputs and existing evidence are reviewed through bounded tools and display surfaces, while later execution capabilities remain gated.

Historical Day and Phase records remain under docs/. They are retained as engineering evidence, not reproduced as a chronological diary in this release README.

Architecture Overview

The current reviewer-facing architecture has four layers.

Validation and report layer

Python modules implement deterministic validation, parsing, report generation, and task metadata. The unified entry point is:

network_lab.py

The task catalog distinguishes safety and execution modes. A task name or catalog entry is descriptive metadata; it is not automatic authorization to run a live workflow.

Evidence layer

Supported workflows produce or inspect structured artifacts under paths such as:

reports/
summary/
docs/portfolio_evidence/

Generated runtime reports are generally local and may be absent from a clean checkout. Committed summaries, documentation, tests, and screenshots provide a review path when runtime evidence is unavailable.

Reviewer interfaces

The canonical reviewer entry point is the Flask dashboard:

dashboard_app.py
http://127.0.0.1:5000/

Its current public review surfaces include:

Route	Current purpose
/	Project positioning, Stage-0 status, evidence health, and review links
/reports	Evidence summaries, status filters, safe JSON previews, and bounded artifact links
/commands	Display-only registry and historical execution-record review; no Run or POST control is rendered
/ai-checklist	Static AI and safety review checklist
/ai-intent-reviewer	Static intent, mock-runtime, readiness-gate, and safety evidence

The Next.js Network Automation AI Node is a secondary Stage-0 interface. Its supported default presentation provides bounded committed or local evidence; it does not replace the Flask Quick Start and does not activate provider, model, job, or device execution.

Governance and safety layer

Repository rules are defined in AGENTS.md. The staged automation boundary is described in the Actual Automation Integration Plan.

The repository contains a version-2 workflow governance contract and hardened helper foundation. That contract is declarative and remains inactive until a separate reviewed activation decision.

Repository map

.
├── adapters/                 # adapter boundaries and non-live scaffolding
├── app/                      # secondary Next.js application routes
├── components/               # secondary UI components
├── config/                   # configuration and inert workflow contracts
├── docs/                     # architecture, safety, history, runbooks, evidence
├── scripts/                  # bounded repository and validation helpers
├── summary/                  # committed safe summary artifacts
├── templates/                # canonical Flask dashboard templates
├── tests/                    # Python regression and safety coverage
├── dashboard_app.py          # canonical local reviewer dashboard
├── network_lab.py            # unified task and report entry point
├── requirements.txt          # Python requirements
└── package.json              # secondary Next.js application metadata

Quick Start

1. Clone the repository

git clone https://github.com/Robinlee0929/Network_Automation_Lab.git
cd Network_Automation_Lab

Read AGENTS.md before running project commands. It defines the current safety boundary and validation expectations.

2. Create a Python environment

The repository does not declare one universal Python version. Use a supported local Python environment and create a virtual environment:

python -m venv .venv

Activate it on Windows PowerShell:

.\.venv\Scripts\Activate.ps1

Or on macOS/Linux:

source .venv/bin/activate

Install the committed requirements:

python -m pip install -r requirements.txt

The Flask dashboard requires Flask 3.x as constrained by requirements.txt.

3. Start the canonical dashboard

python dashboard_app.py

Open:

http://127.0.0.1:5000/

Start with the landing page, then open /reports. Use /commands, /ai-checklist, and /ai-intent-reviewer only as their current Stage-0 display/reviewer surfaces. The visible /commands page does not render a Run or POST control.

Stop the Flask server with Ctrl+C.

4. Run local validation

python -m pytest
python network_lab.py --task report-index

pytest exercises the repository regression and safety contracts. report-index scans local report metadata and evidence paths; it does not connect to devices. It may return WARN when optional generated reports are missing, provided there are no failures and the missing items are documented as optional.

Optional secondary interface

The Next.js application is a secondary evidence surface. It requires a usable Node/npm environment and the committed package metadata, but it is not required for the canonical Flask review flow. Node/NVM coexistence setup is outside the August release path. See the canonical Quick Start and demo runbook for the recorded primary/secondary boundary.

An Optional Local AI Recommendation Preview is available only on the secondary /network/ai-actions page when NETWORK_AI_PROVIDER_DEMO_ENABLED=1 is set in .env.local. It also requires OPENAI_API_KEY, which is used only by the server-side provider client. The default remains NETWORK_AI_PROVIDER_DEMO_ENABLED=0, so the canonical Flask Stage-0 demo stays provider-free. The preview classifies a request against the fixed Action Catalog and stops at a sanitized recommendation; it does not create jobs, generate commands, contact devices, or execute network operations.

Legacy/general provider workbenches at /ai, /automation/ai-nodes, and the historical /api/network/ai/analyze-report route remain outside the canonical provider-free Stage-0 reviewer path. They fail closed by default through LEGACY_AI_PROVIDER_ENABLED=0 and require the separate exact local opt-in LEGACY_AI_PROVIDER_ENABLED=1 plus a server-side OPENAI_API_KEY. Enabling them sends submitted text to the configured external provider, so do not use secrets, credentials, private device data, or private lab data. Provider credential presence is not feature authorization, and neither flag grants device, job, command, or configuration-execution capability.

Public Roadmap

Stage 0 is the formally closed public baseline. Its closure is recorded in the Stage 0 Formal Closure. It includes contributor and security guidance, Issue and pull request templates, newcomer-friendly Issues, and protected-main governance through pull requests and Safe CI. Stage 1's planning entry is retained as historical context. The separately authorized, bounded Stage-2 implementation and live proofs now form a closure candidate; the canonical Stage model and formal closure candidate record the proof, remaining review gate, and limits.

Stage	Purpose	Status
Stage 0 — Closed public baseline	Mock-only, dry-run, report-only, reviewer-visible, fail-closed validation and evidence	CLOSED
Stage 1 — Read-only Lab Integration Planning	Historical planning entry for contracts, allowlists, failure behavior, evidence, and credential boundaries	Historical planning record; see the bounded Stage-2 outcome below
Stage 2 — Narrow Read-only Lab Adapter	Separate bounded MikroTik Lab1 and Lab2 VRRP proofs; target-aware composition; one exact command per authorization; zero retries; normalized evidence; persistent Lab2 startup reconstruction	CLOSURE CANDIDATE — independent closure review and remote Safe CI pending
Stage 3 — Controlled Config Plan Generation	Future human-reviewable configuration plans only; no apply	NOT STARTED / requires separate Owner authorization
Stage 4 — Controlled Change Execution	Permit narrowly approved lab changes with explicit safeguards and evidence	Future / separate gate
Stage 5 — Production-like Platform	Add mature access control, audit, rollback, monitoring, and human approval	Long-term / not currently authorized

The bounded Stage-2 exit is the major-development pause point. The candidate records two independent one-shot operations; the Lab2 proof did not revalidate Lab1 and does not establish overall Lab1/Lab2 VRRP pair health. It also does not establish generic RouterOS or every MikroTik model/version, multi-vendor live execution, arbitrary CLI, write/config automation, automated retries, production HA readiness, fleet orchestration, autonomous remediation, anti-rollback replay protection, or Stage-3 functionality.

A roadmap item, Issue, pull request, merge, date, or milestone does not activate a capability. Every Stage advancement requires separate explicit authorization and validation. Live-device access, SSH, NETCONF, RESTCONF, configuration changes, production execution, secrets handling, provider/model integration, and autonomous execution therefore remain unauthorized by this roadmap.

Core Capabilities

Evidence discovery and presentation

• Index local JSON, HTML, text, image, and documentation evidence.
• Show explicit PASS, FAIL, WARN, MISSING, UNKNOWN, UNAVAILABLE, ERROR, and BLOCKED states where applicable.
• Keep evidence availability separate from validation quality.
• Render bounded summaries rather than arbitrary raw object projection.
• Constrain report links and previews to expected local evidence locations.

Network-validation portfolio coverage

The repository contains code and retained evidence for:

• MikroTik baseline and setup validation;
• Cisco topology validation;
• iperf3 performance and regression reporting;
• WireGuard planning, validation, and evidence;
• HA/VRRP topology, dry-run planning, and retained validation evidence;
• unified task metadata, report indexing, and portfolio demo flows.

Some historical workflows describe read-only or guarded-live lab operations. They are not part of the default August reviewer path and do not grant present operational authority.

Reviewer-oriented AI evidence

The AI-related surfaces demonstrate deterministic intent classification, mock-runtime decisions, dry-run plans, reviewer approval envelopes, audit records, safety gates, and fixed-template summaries. They remain evidence and review aids:

• no model invocation is required for the supported review flow;
• no mapped task is automatically executed;
• no provider or secret is activated;
• no direct device command is generated or run.

Quality and safety coverage

• Python unit and regression tests;
• TypeScript component tests for the secondary interface;
• type checking, lint, and production-build checks in the broader validation lanes;
• negative tests for rejected and unavailable states;
• report-index visibility and status handling;
• narrow-screen and accessibility presentation coverage;
• explicit no-execution and no-live-device evidence.

Typical User / Reviewer Flow

1. Read this README and AGENTS.md.
2. Create the Python environment and start python dashboard_app.py.
3. Open the landing page to understand the project, Stage-0 baseline, and evidence health.
4. Use /reports to inspect available summaries, status filters, safe previews, and missing-evidence states.
5. Review /commands, /ai-checklist, and /ai-intent-reviewer as display-only or static reviewer evidence.
6. Run python -m pytest and python network_lab.py --task report-index when local validation is desired.
7. Inspect relevant reports/, summary/, or linked documentation artifacts.
8. Stop the local dashboard with Ctrl+C.

For a shorter portfolio walkthrough, follow the Public Reviewer Walkthrough. If Flask is unavailable, use the current-suitable home, reports, and AI checklist screenshots under:

docs/demo/day52_offline_demo_package/screenshots/

The retained dashboard_commands.png is historical, superseded evidence of the pre-display-only command UI. Do not use it as evidence of the current /commands surface.

Safety Boundaries

The August release remains the formally closed Stage 0 baseline. Its supported reviewer path is local, report-oriented, dry-run/mock-only, and display-only. Closure changes the delivery-stage status, not the operational safety boundary.

Currently supported safe paths

• Read committed source, tests, documentation, summaries, and screenshots.
• Start the local Flask reviewer dashboard.
• Browse the dashboard GET-oriented review surfaces.
• Inspect bounded local report metadata and safe previews.
• Run deterministic unit/regression tests.
• Run the report-only report-index task.
• Review dry-run, mock, and historical evidence without contacting a device.

Deferred or gated capabilities

The release grants no automatic authority for:

• live-device access;
• SSH, NETCONF, RESTCONF, or equivalent device protocols;
• configuration backup, apply, change, reset, reboot, enable, or disable;
• provider, external API, or model calls;
• credentials or secrets handling;
• arbitrary command execution;
• queue, scheduler, worker, broker, or autonomous agent loops;
• production execution paths.

Any additional live attempt or scope expansion requires separate task-specific Owner approval and the applicable safety gates. The completed Stage-2 attempt is historical evidence, not reusable authorization. An MIT software license permits code use under its terms; it does not override these operational safety boundaries.

Validation / Quality Gates

The standard repository validation commands are:

python -m pytest
python network_lab.py --task report-index

Additional TypeScript checks used by broader product or release lanes are:

npm run test:unit
npm run typecheck
npm run lint
npm run build

These Node checks apply to the secondary interface and are not required merely to open the canonical Flask review path.

Interpreting report status

Status	Meaning
PASS	Required evidence exists and the checked condition passed
FAIL	A required condition failed or required evidence is invalid
WARN	A non-blocking issue or documented optional-evidence gap exists
MISSING	An expected local generated artifact is absent
UNKNOWN	Evidence exists but exposes no supported status field
UNAVAILABLE	The source or bounded projection cannot currently be used
ERROR	Evidence could not be processed safely
BLOCKED	A safety or authorization boundary prevented the action

Generated reports/ content is generally local and ignored by Git. A clean checkout may therefore show missing optional reports. Treat a report-index warning as acceptable only when fail=0 and every missing item is optional and explained.

Release-wide regression, CI diagnosis, and final acceptance are separate August release lanes; they are not performed by documentation-only changes.

Current Release Status

Area	Current status (August baseline with Stage-2 closure candidate)
Stage-0 Network Automation Lab	CLOSED at main@aff250735ade18e4c274be8ac53c9672bb2cb07f
Stage-1 Read-only Lab Integration Planning	Historical planning-entry record; see the Stage-2 closure candidate
Stage-2 bounded MikroTik VRRP validation	Lab1 historical proof retained; Lab2 proof PASS/CLOSED on repository baseline ea73196281e38a01af7bf959cc5e1bc60b0b2499; persistent Lab2 startup reconstruction and independent binding review PASS; overall Stage 2 is a CLOSURE CANDIDATE
Dual-Lab AI Query	NOT IMPLEMENTED / not authorized; eligible only as future work after formal Stage-2 closure
Stage 3	NOT STARTED / requires separate Owner authorization
Canonical reviewer interface	Flask dashboard on 127.0.0.1:5000
Secondary Next.js interface	Available as a bounded Stage-0 evidence surface
WF-01 workflow foundation	Contract and hardened helpers integrated on main
Workflow Version 2	INACTIVE
WF-01-03B	DEFERRED_SECURITY_RESEARCH_BLOCKED
WF-01-03B unfinished research candidate	NOT INCLUDED IN RELEASE
WF-01-03B effect on August closure	Does not block the Stage-0 August release
WF-01-03C through WF-01-03F	Deferred future work / post-release
New project-status infrastructure	Not required; this section is the repository-facing release summary

DEFERRED_SECURITY_RESEARCH_BLOCKED is not a Security PASS, completion, activation, or integration claim. Detailed experimental research evidence is retained separately and is intentionally excluded from the public release.

Known Limitations / Future Work

Current release baseline

The v0.3 release and its bounded post-release maintenance cycle are complete. The current public portfolio path remains the local Stage-0 reviewer experience; future capabilities stay behind their separate authorization and safety gates.

Post-release or deferred

• Continue WF-01-03B security research only after explicit reauthorization.
• Revisit C017/AppContainer research if it remains relevant.
• Plan WF-01-03C through WF-01-03F as separate future work.
• Review and activate workflow v2 only through its later migration, pilot, and acceptance gates.
• Address Node/NVM coexistence only if a later environment-maintenance task requires it.
• Begin any Dual-Lab AI Query work only after Stage-2 formal closure and a separate authorized task. The completed Lab1 and Lab2 proofs grant no future live authority.
• Keep the post-merge Safe CI maintenance findings OPEN: npm has 5 vulnerabilities (2 moderate, 2 high, 1 critical), and Next.js emitted 7 filesystem-tracing warnings. These are non-Stage-2-blocking maintenance items; the Stage-2 closure candidate does not resolve them.

Current limitations also include variable local report availability, no guarantee that every clean checkout contains generated evidence, and a deliberately non-executing public review path.

Documentation Index

Start here

• Contributing guide
• Security policy
• Repository rules and task safety
• Public Reviewer Walkthrough
• Canonical Quick Start and demo runbook
• Accepted Stage-0 user-facing baseline
• Stage 0 formal closure
• Stage 2 formal closure candidate

Architecture and safety

• AI-assisted human-guided network testing architecture
• Actual automation integration plan and Stage model
• Workflow governance foundation planning record

Evidence and usage

• Portfolio Evidence Guide
• Offline demo kit
• Portfolio demo script
• Traditional Chinese portfolio demo script
• v0.2 demo handoff guide

Historical engineering records

• Roadmap and Day records
• Phase 2A–2O records
• Release records
• Portfolio evidence history

Historical records describe the state and authorization boundary at the time they were written. Use Current Release Status above and the canonical Stage model for the August baseline and subsequent bounded Stage-2 closure candidate.

This project is distributed under the MIT License.