diff --git a/.gitignore b/.gitignore index 7a98396a..6acab444 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ docs/images/.DS_Store .DS_Store -venv/ \ No newline at end of file +venv/ +scratch \ No newline at end of file diff --git a/docs/netbox-assurance/images/Assurance_all_deviations.png b/docs/netbox-assurance/images/Assurance_all_deviations.png new file mode 100644 index 00000000..85656a1c Binary files /dev/null and b/docs/netbox-assurance/images/Assurance_all_deviations.png differ diff --git a/docs/netbox-assurance/images/Assurance_archived_deviations.png b/docs/netbox-assurance/images/Assurance_archived_deviations.png new file mode 100644 index 00000000..29d92ced Binary files /dev/null and b/docs/netbox-assurance/images/Assurance_archived_deviations.png differ diff --git a/docs/netbox-assurance/images/Assurance_deviation_types.png b/docs/netbox-assurance/images/Assurance_deviation_types.png new file mode 100644 index 00000000..4854be31 Binary files /dev/null and b/docs/netbox-assurance/images/Assurance_deviation_types.png differ diff --git a/docs/netbox-assurance/images/assurance-apply.png b/docs/netbox-assurance/images/assurance-apply.png new file mode 100644 index 00000000..a662af53 Binary files /dev/null and b/docs/netbox-assurance/images/assurance-apply.png differ diff --git a/docs/netbox-assurance/images/assurance-console-install.png b/docs/netbox-assurance/images/assurance-console-install.png new file mode 100644 index 00000000..2d8397a4 Binary files /dev/null and b/docs/netbox-assurance/images/assurance-console-install.png differ diff --git a/docs/netbox-assurance/images/assurance-detail-apply-confirm.png b/docs/netbox-assurance/images/assurance-detail-apply-confirm.png new file mode 100644 index 00000000..164c7986 Binary files /dev/null and b/docs/netbox-assurance/images/assurance-detail-apply-confirm.png differ diff --git a/docs/netbox-assurance/images/assurance-detail-changes.png b/docs/netbox-assurance/images/assurance-detail-changes.png new file mode 100644 index 00000000..61293966 Binary files /dev/null and b/docs/netbox-assurance/images/assurance-detail-changes.png differ diff --git a/docs/netbox-assurance/images/assurance-detail.png b/docs/netbox-assurance/images/assurance-detail.png new file mode 100644 index 00000000..b2225f9c Binary files /dev/null and b/docs/netbox-assurance/images/assurance-detail.png differ diff --git a/docs/netbox-assurance/images/assurance-detail2.png b/docs/netbox-assurance/images/assurance-detail2.png new file mode 100644 index 00000000..2c4c9a08 Binary files /dev/null and b/docs/netbox-assurance/images/assurance-detail2.png differ diff --git a/docs/netbox-assurance/images/assurance-ignore.png b/docs/netbox-assurance/images/assurance-ignore.png new file mode 100644 index 00000000..9a8648ef Binary files /dev/null and b/docs/netbox-assurance/images/assurance-ignore.png differ diff --git a/docs/netbox-assurance/images/assurance-main-page.png b/docs/netbox-assurance/images/assurance-main-page.png new file mode 100644 index 00000000..c33cc797 Binary files /dev/null and b/docs/netbox-assurance/images/assurance-main-page.png differ diff --git a/docs/netbox-assurance/images/assurance-rediff.png b/docs/netbox-assurance/images/assurance-rediff.png new file mode 100644 index 00000000..9b5ff952 Binary files /dev/null and b/docs/netbox-assurance/images/assurance-rediff.png differ diff --git a/docs/netbox-assurance/images/assurance_active_deviations_hover_on_chart_detail.png b/docs/netbox-assurance/images/assurance_active_deviations_hover_on_chart_detail.png new file mode 100644 index 00000000..797ca13f Binary files /dev/null and b/docs/netbox-assurance/images/assurance_active_deviations_hover_on_chart_detail.png differ diff --git a/docs/netbox-assurance/images/assurance_deviation_applied_after_selecting_apply_change.png b/docs/netbox-assurance/images/assurance_deviation_applied_after_selecting_apply_change.png new file mode 100644 index 00000000..818b0cbb Binary files /dev/null and b/docs/netbox-assurance/images/assurance_deviation_applied_after_selecting_apply_change.png differ diff --git a/docs/netbox-assurance/images/assurance_deviations_active_bulk_options_bottom.png b/docs/netbox-assurance/images/assurance_deviations_active_bulk_options_bottom.png new file mode 100644 index 00000000..d1adbc39 Binary files /dev/null and b/docs/netbox-assurance/images/assurance_deviations_active_bulk_options_bottom.png differ diff --git a/docs/netbox-assurance/images/diode_credentials.png b/docs/netbox-assurance/images/diode_credentials.png new file mode 100644 index 00000000..cc449b1a Binary files /dev/null and b/docs/netbox-assurance/images/diode_credentials.png differ diff --git a/docs/netbox-assurance/images/diode_set_credentials.png b/docs/netbox-assurance/images/diode_set_credentials.png new file mode 100644 index 00000000..80bef776 Binary files /dev/null and b/docs/netbox-assurance/images/diode_set_credentials.png differ diff --git a/docs/netbox-assurance/images/diode_settings_endpoint.png b/docs/netbox-assurance/images/diode_settings_endpoint.png new file mode 100644 index 00000000..b77b29ba Binary files /dev/null and b/docs/netbox-assurance/images/diode_settings_endpoint.png differ diff --git a/docs/netbox-assurance/index.md b/docs/netbox-assurance/index.md index 6670aedd..9b09c9a7 100644 --- a/docs/netbox-assurance/index.md +++ b/docs/netbox-assurance/index.md @@ -1,28 +1,42 @@ -NetBox Cloud -NetBox Enterprise +Enterprise -!!! info "*Coming early 2025*" - Be among the first to experience **NetBox Assurance**. [Sign up](https://netboxlabs.com/netbox-assurance/) to be notified when we launch. +!!! note "NetBox Cloud Support" + NetBox Cloud support coming early July 2025. -NetBox Assurance empowers organizations to continuously detect and address network drift by identifying deviations between the intended state in NetBox and the actual state of the network. It extends NetBox with automated deviation detection and corrective actions, helping teams maintain a consistent and reliable network infrastructure. +NetBox Assurance allows you to control which data goes into NetBox by detecting and managing "operational drift"β€”the difference between your intended network state documented in NetBox and the actual operational state of your network infrastructure. ## Key Features -- **Deviation Detection**: Identify configuration drift between NetBox and the network. -- **Efficient Remediation**: Correct detected deviations through guided workflows. -- **Seamless Integration**: Enhance NetBox with continuous network validation and state synchronization. -- **Detailed Reports**: Generate actionable reports highlighting network consistency and detected deviations. +- **Operational Drift Detection**: Identify differences between NetBox's intended state and actual network state +- **Data Ingestion Control**: Review and approve data before it enters NetBox, maintaining data quality +- **Seamless Integration**: Works with NetBox Discovery and supports custom integrations via the Diode SDK +- **Change Set Management**: Review proposed updates and apply them to NetBox branches or ignore as needed +- **Audit Trail**: Track all changes and decisions for compliance and operational history ## How It Works -NetBox Assurance continuously compares the documented or intended network state stored in NetBox with the observed network state being provided by NetBox Discovery and other network data sources. When deviations are detected, workflows allow effecient remediation of deviations by updating NetBox or by taking corrective actions on the network. +NetBox Assurance follows a structured four-step workflow: + +1. **Data Ingestion**: Network information flows in from NetBox Discovery, direct device interrogation, or other sources via the Diode SDK +2. **Analysis & Comparison**: Ingested data is analyzed against existing NetBox records to identify operational drift +3. **Deviation Review**: Review detected deviations and examine proposed change sets +4. **Action & Resolution**: Apply changes to NetBox, recalculate drift, or ignore deviations as needed + +![NetBox Assurance Main Interface](images/assurance-main-page.png) ## Use Cases -- **Network Drift Detection**: Ensure network configurations remain consistent with the source of truth. -- **Compliance Audits**: Support compliance efforts by detecting unauthorized changes. -- **Incident Prevention**: Identify and address deviations before they cause major disruptions. +- **Day 1 - Initial NetBox Population**: Control data quality while rapidly populating NetBox with discovery data +- **Day 1.5 - Improving Network Maturity**: Maintain operations while gradually improving documentation and automation processes +- **Day 2 - Operational Excellence**: Proactively detect and resolve operational drift to maintain network reliability + +## Getting Started + +1. **[Quickstart Guide](quickstart-guide.md)**: Get up and running quickly with NetBox Assurance +2. **[Assurance Workflows](workflows/index.md)**: Configure drift detection and review processes +3. **[Data Ingestion](monitoring/index.md)**: Set up data sources from NetBox Discovery and other systems ## Support and Resources -- **Documentation**: Until NetBox Assurance is officially released, please refer to the [Diode](../netbox-extensions/diode/index.md) project documentation. -- **Community Support**: Connect with the community on [Slack](https://netdev.chat/) in the `#netbox` channel. +- **Community Support**: Connect with the community on [Slack](https://netdev.chat/) in the `#netbox` channel +- **Documentation**: Additional resources and integration guides available in related sections +- **GitHub Repository**: Find NetBox Discovery integration [here](https://github.com/netboxlabs/orb-agent) --- -With **NetBox Assurance**, teams can detect, report, and resolve network deviations in real time, ensuring a consistent and reliable network environment through continuous validation and corrective actions. \ No newline at end of file +By leveraging **NetBox Assurance**, organizations can maintain accurate network documentation, reduce operational risk, and build confidence in their network automation initiatives through continuous validation and drift detection. \ No newline at end of file diff --git a/docs/netbox-assurance/monitoring/index.md b/docs/netbox-assurance/monitoring/index.md new file mode 100644 index 00000000..79c0247b --- /dev/null +++ b/docs/netbox-assurance/monitoring/index.md @@ -0,0 +1,92 @@ +Enterprise + +# Data Ingestion and Analysis + +!!! note "NetBox Cloud Support" + NetBox Cloud support coming early July 2025. + +NetBox Assurance ingests network data from multiple sources and analyzes it against your NetBox documentation to identify operational drift. This process ensures your network documentation stays accurate and up-to-date. + +## Data Sources + +### NetBox Discovery Integration +The primary source for automated network data collection: + +- **Network Discovery**: Automated discovery of network devices and topology +- **Device Discovery**: Detailed device inventory and configuration collection +- **Controller Integrations**: VMware vCenter, Cisco Catalyst Center, Juniper Mist, Microsoft DHCP, AWS VPC IPAM + +![Diode Configuration](../images/diode_settings_endpoint.png) + +### Diode SDK Integration +Public API for custom data sources and integrations: + +- **Python and Golang SDKs**: Development kits for building custom integrations +- **Monitoring Systems**: Prometheus, Grafana, DataDog, Splunk +- **Inventory Systems**: CMDBs, spreadsheets, asset management systems +- **Automation Tools**: Ansible, Terraform, custom scripts + +![Diode Credentials](../images/diode_credentials.png) + +### Direct API Access +Send data directly to NetBox Assurance: +- **REST API**: Standard HTTP-based data submission +- **Bulk Operations**: Efficient handling of large data sets +- **Real-time Updates**: Immediate processing of network changes +- **Idempotent Operations**: Safe to retry without duplicating data + +## Analysis Process + +### Operational Drift Detection +NetBox Assurance compares ingested data against existing NetBox records to identify: + +- **Missing Objects**: Network elements discovered but not documented in NetBox +- **Obsolete Objects**: NetBox entries that no longer exist in the actual network +- **Configuration Drift**: Differences in device attributes, IP addresses, or relationships +- **Topology Changes**: New connections or removed links between devices + +### Data Quality Control +Before data enters NetBox, Assurance provides: + +- **Change Preview**: See exactly what would be modified in NetBox +- **Impact Analysis**: Understand the scope of proposed changes +- **Conflict Resolution**: Handle overlapping or contradictory data +- **Validation Rules**: Ensure data meets organizational standards + +![Deviation Review](../images/assurance-detail.png) + +## Integration Patterns + +### Continuous Monitoring +Real-time observation of network state: +- **Event-driven Updates**: Process changes as they occur +- **Low-latency Detection**: Immediate identification of drift +- **Critical Infrastructure Focus**: Priority monitoring for essential systems + +### Scheduled Collection +Periodic comprehensive data gathering: +- **Daily Discovery Runs**: Regular network scans +- **Weekly Compliance Audits**: Systematic validation of network state +- **Monthly Trend Analysis**: Long-term drift pattern identification + +### Hybrid Approach +Combination of real-time and scheduled monitoring: +- **Critical Systems**: Continuous monitoring for core infrastructure +- **Standard Systems**: Scheduled collection for routine equipment +- **Flexible Policies**: Different monitoring strategies per device type + +## Getting Started + +1. **Configure NetBox Discovery**: Set up automated network and device discovery +2. **Enable Diode Integration**: Connect monitoring systems and data sources +3. **Define Data Sources**: Specify which systems should send data to Assurance +4. **Set Collection Schedules**: Determine how frequently to gather network data +5. **Review Initial Results**: Examine first deviations and tune detection sensitivity + +## Best Practices + +- **Start with Discovery**: Use NetBox Discovery as your primary data source +- **Gradual Expansion**: Add custom integrations incrementally +- **Data Validation**: Verify data quality before large-scale ingestion +- **Monitor Performance**: Track ingestion rates and processing times +- **Document Sources**: Maintain clear records of all data integration points \ No newline at end of file diff --git a/docs/netbox-assurance/quickstart-guide.md b/docs/netbox-assurance/quickstart-guide.md new file mode 100644 index 00000000..4ed66990 --- /dev/null +++ b/docs/netbox-assurance/quickstart-guide.md @@ -0,0 +1,63 @@ +Enterprise + +# NetBox Assurance Quickstart Guide + +!!! note "NetBox Cloud Support" + NetBox Cloud support coming early July 2025. + +This quickstart guide will help you get NetBox Assurance up and running to detect and manage operational drift between your intended network state in NetBox and the actual state of your network infrastructure. + +## Prerequisites + +- NetBox Enterprise installation with Assurance enabled +- Network data sources configured (NetBox Discovery recommended) +- Administrative access to NetBox Enterprise +- Network devices accessible for data collection + +## Installation and Setup + +### Step 1: Enable NetBox Assurance + +During NetBox Enterprise installation, ensure NetBox Assurance is selected in the configuration screen: + +![NetBox Enterprise Installation](images/assurance-console-install.png) + +### Step 2: Access NetBox Assurance + +Once installed, NetBox Assurance appears in your NetBox navigation sidebar: + +![NetBox Assurance Interface](images/assurance-main-page.png) + +### Step 3: Configure Data Sources + +Set up data ingestion from one or more sources: + +- **NetBox Discovery**: Leverage existing network and device discovery data +- **Diode SDK**: Configure custom integrations with monitoring systems, CMDBs, or other data sources +- **Direct API**: Send data directly from scripts or automation tools + +### Step 4: Review Your First Deviations + +Once data flows in, Assurance will detect operational drift and present deviations for review: + +![Deviations Dashboard](images/Assurance_all_deviations.png) + +### Step 5: Take Action + +For each deviation, you can: +- **Apply**: Update NetBox with the discovered network state +- **Ignore**: Mark as acceptable deviation +- **Recalculate**: Refresh the comparison after making changes + +![Apply Changes](images/assurance-detail-apply-confirm.png) + +## Next Steps + +- **[Configure Workflows](workflows/index.md)**: Set up automated drift detection rules +- **[Data Ingestion Setup](monitoring/index.md)**: Configure additional data sources +- **[Workflow Configuration](workflows/configuration.md)**: Customize detection and review processes + +## Getting Help + +- **Community Support**: Join the [NetBox Slack](https://netdev.chat/) `#netbox` channel +- **Documentation**: Explore the detailed workflow and configuration guides \ No newline at end of file diff --git a/docs/netbox-assurance/workflows/configuration.md b/docs/netbox-assurance/workflows/configuration.md new file mode 100644 index 00000000..965402e3 --- /dev/null +++ b/docs/netbox-assurance/workflows/configuration.md @@ -0,0 +1,105 @@ +Enterprise + +# Workflow Configuration + +!!! note "NetBox Cloud Support" + NetBox Cloud support coming early July 2025. + +This page covers how to configure NetBox Assurance workflows to manage data ingestion and detect operational drift from the intended state in NetBox. + +## Configuration Overview + +NetBox Assurance workflows are configured through the NetBox interface and consist of: + +- **Monitoring Targets**: Devices, services, or network segments to monitor +- **Detection Rules**: Criteria that define what constitutes a deviation +- **Actions**: Responses to execute when deviations are detected +- **Schedules**: When and how often to run the workflow + +## Basic Workflow Configuration + +### 1. Define Monitoring Targets + +Specify which network elements to monitor: + +```yaml +targets: + - device_role: "router" + site: "datacenter-01" + - device_type: "cisco-catalyst-9300" + tenant: "production" +``` + +### 2. Set Detection Rules + +Configure the conditions that trigger deviation alerts: + +```yaml +rules: + - name: "Configuration Drift" + type: "config_comparison" + threshold: "any_change" + - name: "Interface State" + type: "operational_state" + expected: "up" +``` + +### 3. Configure Actions + +Define what happens when deviations are detected: + +```yaml +actions: + - type: "alert" + severity: "warning" + recipients: ["network-team@example.com"] + - type: "create_ticket" + system: "servicenow" + priority: "medium" +``` + +## Advanced Configuration + +### Custom Validation Rules + +Create custom rules for organization-specific requirements: + +```yaml +custom_rules: + - name: "VLAN Consistency" + description: "Ensure VLANs match NetBox configuration" + script: | + # Custom validation logic + if device.vlans != netbox.vlans: + return deviation_found("VLAN mismatch detected") +``` + +### Remediation Workflows + +Configure automatic remediation for common issues: + +```yaml +remediation: + - condition: "interface_down" + action: "restart_interface" + approval_required: false + - condition: "config_drift" + action: "restore_config" + approval_required: true +``` + +## Best Practices + +- Start with read-only monitoring before enabling remediation +- Test workflows in non-production environments first +- Use appropriate notification channels for different severity levels +- Regularly review and update detection rules +- Monitor workflow performance and adjust schedules as needed + +## Troubleshooting + +Common configuration issues and solutions: + +- **Workflow not triggering**: Check monitoring target configuration and device accessibility +- **False positives**: Refine detection rules to reduce noise +- **Performance issues**: Adjust monitoring frequency and target scope \ No newline at end of file diff --git a/docs/netbox-assurance/workflows/deviation-detection.md b/docs/netbox-assurance/workflows/deviation-detection.md new file mode 100644 index 00000000..0b73eb74 --- /dev/null +++ b/docs/netbox-assurance/workflows/deviation-detection.md @@ -0,0 +1,156 @@ +Enterprise + +# Deviation Detection + +!!! note "NetBox Cloud Support" + NetBox Cloud support coming early July 2025. + +Deviation detection is the core capability of NetBox Assurance, identifying operational drift between the intended network state documented in NetBox and the actual operational state of your network infrastructure. + +## Types of Operational Drift + +!!! note "Important" + NetBox Assurance detects "operational drift" (differences between NetBox data and actual network state), not "configuration drift" (differences between running config and intended config). + +### Network State Deviations +- **Device Information**: Device models, software versions, or hardware components that differ from NetBox records +- **Interface States**: Interface operational status that differs from expected values +- **Network Topology**: Physical or logical connections that don't match NetBox documentation + +### Topology Deviations +- **Physical Connections**: Cable connections that don't match documented topology +- **Interface Status**: Interfaces in unexpected up/down states +- **VLAN Assignments**: VLAN configurations that differ from NetBox + +### Inventory Discrepancies +- **Missing Devices**: Devices documented in NetBox but not found on network +- **Undocumented Devices**: Devices discovered on network but not in NetBox +- **Hardware Changes**: Component changes not reflected in NetBox + +## Detection Methods + +### Real-time Monitoring +Continuous monitoring of network state changes: + +```yaml +detection: + mode: "real-time" + sources: + - snmp_polling + - syslog_monitoring + - api_integration + frequency: "30s" +``` + +### Scheduled Validation +Periodic comprehensive validation checks: + +```yaml +detection: + mode: "scheduled" + schedule: "0 */6 * * *" # Every 6 hours + full_scan: true + sources: + - configuration_backup + - discovery_agent + - network_scanning +``` + +### Event-driven Detection +Triggered by specific network events: + +```yaml +detection: + mode: "event-driven" + triggers: + - config_change_notification + - device_reboot + - interface_state_change +``` + +## Detection Rules + +### Standard Rules +Pre-built rules for common deviation scenarios: + +- **Interface State Validation**: Ensure interface operational states match expected values +- **IP Address Consistency**: Verify IP assignments match NetBox records +- **Routing Table Validation**: Check routing entries against expected topology +- **Access Control Validation**: Ensure security policies are correctly applied + +### Custom Rules +Organization-specific validation logic: + +```python +def validate_vlan_consistency(device, netbox_data): + """Custom rule to validate VLAN configuration""" + device_vlans = device.get_vlans() + netbox_vlans = netbox_data.get_vlans() + + deviations = [] + for vlan_id, vlan_config in device_vlans.items(): + if vlan_id not in netbox_vlans: + deviations.append(f"Undocumented VLAN {vlan_id} found") + elif vlan_config != netbox_vlans[vlan_id]: + deviations.append(f"VLAN {vlan_id} configuration mismatch") + + return deviations +``` + +## Severity Levels + +### Critical +- Security policy violations +- Complete service outages +- Major configuration errors + +### Warning +- Minor configuration drift +- Performance degradation indicators +- Compliance violations + +### Informational +- Documentation updates needed +- Optimization opportunities +- Preventive maintenance alerts + +## Deviation Reporting + +### Alert Format +```json +{ + "severity": "warning", + "device": "sw01.datacenter.example.com", + "rule": "Interface State Validation", + "deviation": "Interface Gi0/1 is down, expected up", + "timestamp": "2025-01-15T10:30:00Z", + "remediation_suggested": "Check physical connection", + "workflow_id": "assurance-001" +} +``` + +### Reporting Options +- **Real-time Alerts**: Immediate notifications for critical deviations +- **Daily Summaries**: Consolidated reports of all detected deviations +- **Trend Analysis**: Historical deviation patterns and trends +- **Compliance Reports**: Regulatory compliance status reports + +## Best Practices + +### Rule Configuration +- Start with conservative thresholds to avoid alert fatigue +- Gradually refine rules based on operational experience +- Use appropriate severity levels for different types of deviations +- Include context and remediation guidance in alerts + +### Monitoring Strategy +- Prioritize critical infrastructure for real-time monitoring +- Use scheduled validation for comprehensive periodic checks +- Implement event-driven detection for immediate response to changes +- Balance monitoring frequency with system performance + +### Integration +- Connect with existing alerting and ticketing systems +- Integrate with configuration management tools +- Use APIs for custom integrations and automation +- Maintain audit trails for compliance requirements \ No newline at end of file diff --git a/docs/netbox-assurance/workflows/index.md b/docs/netbox-assurance/workflows/index.md new file mode 100644 index 00000000..565ff471 --- /dev/null +++ b/docs/netbox-assurance/workflows/index.md @@ -0,0 +1,80 @@ +Enterprise + +# Assurance Workflows + +!!! note "NetBox Cloud Support" + NetBox Cloud support coming early July 2025. + +NetBox Assurance workflows provide structured processes for detecting, reviewing, and resolving operational drift between your intended network state in NetBox and the actual network state discovered from various data sources. + +## Core Workflow Process + +NetBox Assurance follows a four-step workflow that puts you in complete control of your network data: + +![Workflow Process](../images/Assurance_all_deviations.png) + +### 1. Data Ingestion +Network information flows into NetBox Assurance from multiple sources: +- **NetBox Discovery**: Automated network and device discovery +- **Controller Integrations**: VMware vCenter, Cisco Catalyst Center, Juniper Mist, etc. +- **Diode SDK**: Custom integrations with monitoring systems, CMDBs, spreadsheets +- **Direct API**: Manual or scripted data submission + +### 2. Analysis & Comparison +Ingested data is automatically compared against existing NetBox records to identify: +- **Missing Objects**: Items found in the network but not documented in NetBox +- **Extra Objects**: Items in NetBox that don't exist in the actual network +- **Attribute Differences**: Configuration or state mismatches between systems + +### 3. Deviation Review +Review detected deviations through the Assurance interface: +- **Categorized Deviations**: Organized by type and severity +- **Change Previews**: See exactly what would change in NetBox +- **Bulk Operations**: Process multiple related deviations together +- **Filtering and Search**: Find specific types of drift quickly + +![Deviation Types](../images/Assurance_deviation_types.png) + +### 4. Action & Resolution +Take appropriate action for each deviation: +- **Apply Changes**: Update NetBox with discovered network state +- **Ignore Deviations**: Mark acceptable differences as exceptions +- **Recalculate**: Refresh analysis after manual NetBox changes +- **Archive**: Move resolved deviations to historical records + +## Workflow Configuration + +### Detection Rules +Configure what constitutes operational drift: +- **Object Types**: Which network objects to monitor +- **Attributes**: Which properties to compare +- **Thresholds**: Sensitivity levels for change detection +- **Exclusions**: Known acceptable differences + +### Review Processes +Establish approval workflows: +- **Assignment Rules**: Route deviations to appropriate team members +- **Approval Chains**: Multi-step review for critical changes +- **Notification Settings**: Alerts for new deviations or escalations +- **SLA Tracking**: Monitor response times and resolution rates + +### Branch Management +Control how changes are applied to NetBox: +- **Main Branch**: Direct updates to production NetBox data +- **User Branches**: Isolated environments for testing changes +- **Merge Policies**: Rules for incorporating branch changes +- **Rollback Procedures**: Undo changes when needed + +## Getting Started + +1. **[Configuration](configuration.md)**: Set up detection rules and approval processes +2. **[Deviation Detection](deviation-detection.md)**: Understand how drift is identified and classified +3. **[Remediation](remediation.md)**: Learn resolution strategies and automation options + +## Best Practices + +- **Start Small**: Begin with a subset of devices or object types +- **Review Regularly**: Establish daily or weekly deviation review cycles +- **Document Decisions**: Use ignore functionality to record acceptable exceptions +- **Monitor Trends**: Track deviation patterns to identify systemic issues +- **Automate Gradually**: Move from manual to automated resolution as confidence grows \ No newline at end of file diff --git a/docs/netbox-assurance/workflows/remediation.md b/docs/netbox-assurance/workflows/remediation.md new file mode 100644 index 00000000..64c3a587 --- /dev/null +++ b/docs/netbox-assurance/workflows/remediation.md @@ -0,0 +1,222 @@ +Enterprise + +# Remediation Workflows + +!!! note "NetBox Cloud Support" + NetBox Cloud support coming early July 2025. + +Remediation workflows automatically respond to detected deviations, either by correcting the issue directly or by initiating processes to address the deviation. + +## Remediation Types + +### Automatic Remediation +Direct correction of detected deviations without human intervention: + +```yaml +remediation: + - name: "Interface Recovery" + trigger: "interface_down" + action: "restart_interface" + conditions: + - "interface_administratively_down == false" + - "physical_layer_ok == true" + approval_required: false +``` + +### Guided Remediation +Providing step-by-step guidance for manual correction: + +```yaml +remediation: + - name: "Configuration Drift Correction" + trigger: "config_drift_detected" + action: "provide_guidance" + steps: + - "Review configuration differences" + - "Validate proposed changes" + - "Apply configuration update" + - "Verify remediation success" +``` + +### Workflow Triggers +Initiating business processes for complex issues: + +```yaml +remediation: + - name: "Hardware Failure Response" + trigger: "hardware_failure" + action: "create_ticket" + workflow: + system: "servicenow" + priority: "high" + assignment_group: "network_operations" + include_diagnostics: true +``` + +## Common Remediation Actions + +### Network Device Actions +- **Interface Reset**: Restart interfaces that are administratively down +- **Configuration Restore**: Restore known-good configurations +- **Service Restart**: Restart network services experiencing issues +- **Routing Update**: Correct routing table entries + +### NetBox Synchronization +- **Update Records**: Sync NetBox data with discovered network state +- **Create Missing Objects**: Add undocumented devices or interfaces +- **Deprecate Removed Items**: Mark removed network components as inactive + +### Notification and Escalation +- **Alert Generation**: Send notifications to appropriate teams +- **Ticket Creation**: Create service desk tickets for manual intervention +- **Escalation**: Escalate unresolved issues to higher-level support + +## Remediation Configuration + +### Basic Configuration +```yaml +remediation_policy: + name: "Standard Network Remediation" + enabled: true + approval_required: false + + actions: + - type: "interface_restart" + conditions: + - "administrative_status == down" + - "operational_status == down" + max_attempts: 3 + retry_delay: "30s" + + - type: "config_sync" + conditions: + - "config_drift_detected == true" + - "deviation_severity <= warning" + approval_required: true +``` + +### Advanced Configuration +```yaml +remediation_policy: + name: "Critical Infrastructure Remediation" + enabled: true + + conditions: + device_role: ["core_router", "core_switch"] + + actions: + - type: "automated_recovery" + max_impact: "single_device" + approval_required: true + approvers: ["network_manager", "operations_lead"] + + - type: "rollback_config" + trigger: "config_validation_failed" + rollback_window: "24h" + + - type: "emergency_notification" + trigger: "critical_failure" + recipients: ["on_call_engineer"] + escalation_delay: "5m" +``` + +## Safety Mechanisms + +### Approval Workflows +- **Multi-level Approval**: Require multiple approvals for high-impact changes +- **Time-based Approval**: Automatic approval after specified time periods +- **Risk Assessment**: Evaluate potential impact before remediation + +### Rollback Capabilities +- **Configuration Snapshots**: Automatic backup before changes +- **Rollback Triggers**: Automatic rollback on validation failure +- **Manual Rollback**: Operator-initiated rollback procedures + +### Impact Limitation +- **Maintenance Windows**: Restrict remediation to approved time periods +- **Device Limits**: Limit concurrent remediation actions +- **Circuit Protection**: Prevent remediation on critical circuits + +## Monitoring and Reporting + +### Remediation Tracking +```json +{ + "remediation_id": "rem-001", + "deviation_id": "dev-123", + "action": "interface_restart", + "device": "sw01.datacenter.example.com", + "status": "completed", + "started": "2025-01-15T10:30:00Z", + "completed": "2025-01-15T10:31:15Z", + "success": true, + "details": "Interface Gi0/1 successfully restarted" +} +``` + +### Success Metrics +- **Remediation Success Rate**: Percentage of successful automatic remediations +- **Time to Resolution**: Average time from detection to remediation +- **Manual Intervention Rate**: Percentage of deviations requiring manual intervention +- **Rollback Frequency**: Number of remediations requiring rollback + +## Integration Examples + +### ServiceNow Integration +```yaml +integration: + servicenow: + url: "https://company.service-now.com" + authentication: "oauth2" + ticket_creation: + category: "Network" + subcategory: "Infrastructure" + priority_mapping: + critical: "1" + warning: "3" + informational: "4" +``` + +### Slack Integration +```yaml +integration: + slack: + webhook_url: "https://hooks.slack.com/services/..." + channels: + critical: "#network-alerts" + warning: "#network-monitoring" + success: "#network-ops" + message_format: "detailed" +``` + +### Ansible Integration +```yaml +integration: + ansible: + playbook_path: "/opt/netbox-assurance/playbooks" + inventory: "dynamic" + remediation_playbooks: + interface_restart: "restart_interface.yml" + config_restore: "restore_config.yml" + service_restart: "restart_service.yml" +``` + +## Best Practices + +### Remediation Strategy +- Start with read-only monitoring to understand deviation patterns +- Implement least-privilege remediation (minimal changes required) +- Use staged rollouts for new remediation policies +- Maintain detailed audit logs of all remediation actions + +### Risk Management +- Test remediation actions in lab environments first +- Implement appropriate approval workflows for high-impact changes +- Monitor remediation success rates and adjust policies accordingly +- Have rollback procedures ready for all automated actions + +### Operational Excellence +- Provide clear documentation for all remediation actions +- Train operators on manual intervention procedures +- Regular review and update of remediation policies +- Integration with existing change management processes \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index faf00537..39905887 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -137,6 +137,14 @@ nav: - Device Discovery: "netbox-discovery/agent/device_discovery.md" - NetBox Assurance: - NetBox Assurance: "netbox-assurance/index.md" + - Quickstart Guide: "netbox-assurance/quickstart-guide.md" + - Assurance Workflows: + - Overview: "netbox-assurance/workflows/index.md" + - Configuration: "netbox-assurance/workflows/configuration.md" + - Deviation Detection: "netbox-assurance/workflows/deviation-detection.md" + - Remediation: "netbox-assurance/workflows/remediation.md" + - Data Ingestion: + - Overview: "netbox-assurance/monitoring/index.md" - Integrations: - NetBox Ansible Collection: "netbox-integrations/netbox-ansible-collection.md" - pyATS: "netbox-integrations/pyats.md" diff --git a/pr-description.md b/pr-description.md new file mode 100644 index 00000000..e042e326 --- /dev/null +++ b/pr-description.md @@ -0,0 +1,56 @@ +## Overview + +This PR implements comprehensive updates to NetBox Assurance documentation to support the Enterprise launch and prepare for Cloud availability in early July 2025. + +## Key Changes + +### πŸ“ **Documentation Restructure** +- Broke out NetBox Assurance docs into comprehensive structure similar to NetBox Discovery +- Created new sections: quickstart guide, workflows, and data ingestion +- Added proper navigation hierarchy in mkdocs.yml + +### 🏷️ **Product Availability Updates** +- Updated product pills to Enterprise-only (since Enterprise is now available) +- Added simple note about Cloud support coming early July 2025 +- Removed outdated launch messaging since Enterprise is live + +### πŸ“ **Content Alignment** +- Corrected terminology: use 'operational drift' instead of 'configuration drift' +- Aligned all content with authoritative NetBox Assurance knowledge base +- Added proper Diode SDK integration documentation +- Included NetBox Discovery integration details +- Updated workflows to reflect actual user journey (Data Ingestion β†’ Analysis β†’ Review β†’ Action) + + + +## New Documentation Structure + +``` +docs/netbox-assurance/ +β”œβ”€β”€ index.md # Updated main overview +β”œβ”€β”€ quickstart-guide.md # New quick start guide +β”œβ”€β”€ workflows/ # New workflow documentation +β”‚ β”œβ”€β”€ index.md # Workflows overview +β”‚ β”œβ”€β”€ configuration.md # Workflow configuration guide +β”‚ β”œβ”€β”€ deviation-detection.md # Deviation detection details +β”‚ └── remediation.md # Remediation workflows +β”œβ”€β”€ monitoring/ # Renamed to data ingestion +β”‚ └── index.md # Data ingestion overview +└── images/ # Screenshots and assets +``` + +## Testing +- [ ] Local mkdocs build successful +- [ ] Navigation structure verified +- [ ] All internal links working +- [ ] Content accuracy reviewed against knowledge base + +## Related +- Addresses PRD-439 requirements for NetBox Assurance documentation updates +- Prepares documentation for NetBox Enterprise launch (available now) +- Sets foundation for NetBox Cloud support (early July 2025) + +## Next Steps +- Review content accuracy and completeness +- Validate technical details with product team +- Confirm Cloud timeline messaging \ No newline at end of file