ipfreports 2.5.4

A package to generate reports from IP Fabric data

IP Fabric Reports Generator

Overview

The IP Fabric Reports Generator is a powerful Python package designed to streamline the process of creating comprehensive network reports using data from IP Fabric. This tool automates the generation of detailed reports on various aspects of your network infrastructure, providing valuable insights and visualizations.

Compatibility: This tool is compatible with IP Fabric version 7.5 and later. Earlier versions may not work due to API changes.

Integrations or scripts should not be installed directly on the IP Fabric VM via the Command-Line Interface (CLI) unless directly communicated from the IP Fabric Support or Solution Architect teams. Packages can be safely installed as Extensions through the UI. Any action on the CLI using the root, osadmin, or autoboss account may cause irreversible, detrimental changes to the product and can render the system unusable.

Key Features

• Automated Report Generation: Quickly generate detailed reports with minimal manual input.
• Multiple Report Types: Supports various report types, easily extensible for additional reports.
• Data Visualization: Includes pie charts and tables for clear data representation.
• Customizable Templates: Use pre-defined templates or create your own to tailor reports to your needs.
• PDF and HTML Output: Generate reports in both PDF and HTML formats for easy sharing and viewing.
  • CSV Output: Available for specific reports only (Discovery, CVE).
  • XLSX Output: Available for specific reports only (Trunk Mismatch).
• Environment Variable Configuration: Easily configure the tool using environment variables or a .env file.
• Customizable Styles: Choose different CSS styles for your reports.

Available Report Types

To see the full list of available reports, you can use the following command:

ipfreports --list

This will output:

  management-protocol  Report showing the distribution of management protocols across the network or site.
  port-capacity        Report showing the capacity of active network ports in the network or site.
  trunk-mismatch       Report to show the Vlan(s) mismatch for all the trunk ports using the information from switchport (config) and spanning-tree tables.
  overview             Report providing summary data for available sections (Vendors, Device Types, Interfaces, etc).
  overview-compare     Report comparing two IP Fabric snapshots based on Overview Report.
  discovery            Report combining undiscovered IPs from Connectivity Report with CDP/LLDP unmanaged neighbors, and matrix unmanaged neighbors.
  lld                  Per-site Low Level Design (LLD) report: inventory, physical/link/network layer details, and management plane. Requires --site.
  cve                  Report showing CVE vulnerabilities for network devices in a specific site.

Getting Started

Installation

Install the latest release from PyPI:

pip install ipfreports
# or
uv pip install ipfreports

To track the development tip on main, install straight from GitLab:

uv pip install git+https://gitlab.com/ip-fabric/integrations/ipfreports

For local development:

uv sync

Web UI (Docker)

A modern web interface is available for generating reports through a browser. The UI features:

• 🎨 IP Fabric-themed design
• 🔐 API key or cookie-based authentication
• 📊 Interactive report selection and generation
• 📥 Direct PDF/Excel downloads

Quick Start:

# Using Docker Compose (recommended)
docker-compose up -d

# Access the UI at http://localhost:80

For detailed Web UI documentation, see web_ui/README.md.

IP Fabric Extension Deployment

Deploy as an IP Fabric extension for seamless integration.

1. Download the latest extension ZIP from the project's Releases page — pick the latest release and download ipfabric-reports-extension-vX.Y.Z.zip.

2. Upload it to IP Fabric: go to Extensions → Upload and select the downloaded ZIP.

The extension uses cookie-based authentication — no .env file needed on the server.

Building locally? Run bash scripts/build-package.sh to produce a ZIP in dist/. This is intended for development; production deployments should use the published Release asset above.

Performance considerations for large datasets

Reports are generated synchronously and can take several minutes on large networks (thousands of devices, tens of thousands of interfaces / routes). Two consequences when running in extension mode:

• Wait time. A full-network Port Capacity, Discovery, or Overview report on a large snapshot can take 10+ minutes. Extension mode is locked to paginated fetches (streaming=False) because the IP Fabric nginx proxy truncates streaming responses (see SD-808) — paginated requests are reliable but slower, especially on tables with hundreds of thousands of rows.
• Session expiry. The extension authenticates via the IP Fabric session cookie. If the cookie expires while a long report is in progress, the next SDK call will fail mid-report.

Recommendations:

• Use the site filter when generating reports for large environments — per-site reports are dramatically faster and avoid session-expiry risk.
• For full-network reports on very large datasets, prefer the standalone Docker deployment (see Web UI section). It authenticates with a long-lived API token (no session expiry) and can opt into streaming for a large speedup by setting IPF_STREAMING=true in the environment.

Configuration

Set up your environment variables in a .env file or in your system environment:

IPF_URL=https://your-ipfabric-instance.com
IPF_TOKEN=your_token_here
IPF_SNAPSHOT_ID=your_snapshot_id_here
REPORT_TYPE=management-protocol  # or any other available report type
REPORT_STYLE=default_style.css  # Optional: specify a custom CSS file
LOGO_PATH=images/logo.png # Optional: specify a custom logo

# REPORT_SITE is Optional for majority of report types
# REPORT_SITE is Mandatory for the `cve`, `management-protocol`, and `lld` report types
REPORT_SITE=Site Name  

# INVENTORY_FILTER is only available for CVE Report - EXAMPLE={"vendor": ["eq", "arista"], "devType": ["eq", "switch" ]}
INVENTORY_FILTER=None                # IP Fabric Inventory filter (available for some report types only) 

# Special requirements for CVE Report
NVD_API_KEY=api_key # Request at `https://nvd.nist.gov/developers/request-an-api-key`

Usage

Command Line Interface

1. List available report types:

   uv run ipfreports --list
   

2. Generate a specific report:

   uv run ipfreports --type management-protocol
   

   or

   uv run ipfreports --type port-capacity
   

   If no type is specified, it will use the REPORT_TYPE from your environment variables. You will find your reports in the export directory.

3. Specify Site Name:

   uv run ipfreports --type port-capacity --site "Site Name"
   

4. Specify a custom .env file:

   uv run ipfreports --env /path/to/your/.env
   

5. Specify a custom CSS style:

   uv run ipfreports --style custom_style.css
   

   If not specified, it will use the REPORT_STYLE from your environment variables, or default to default_style.css.

6. Enable streaming for faster fetches (advanced):

   uv run ipfreports --type overview --streaming
   

   By default, the tool uses paginated IP Fabric API requests — slower but immune to nginx response truncation on large networks (see SD-808). On smaller deployments, or when reaching IP Fabric directly without a reverse proxy, streaming is significantly faster.

   • --streaming — opt in to streaming for this run.
   • --no-streaming — force the safe paginated path (overrides any env var).
   • IPF_STREAMING=true — opt in via environment variable.

   If you see JSONDecodeError: Unterminated string while streaming, disable it. The default (paginated) is correct for production deployments behind nginx.

Python Script

You can also use the generator in your Python scripts:

from ipfreports import IPFabricReportGenerator

generator = IPFabricReportGenerator()
generator.generate_report()

Or with specific options:

from ipfreports import IPFabricReportGenerator

generator = IPFabricReportGenerator(
    env_file='/path/to/your/.env',
    report_type='port-capacity',
    report_style='custom_style.css',
)
generator.generate_report()

Customizing CSS Styles

For detailed instructions on how to use and customize CSS themes for your reports, please refer to the CSS Styles README.

Extending the Tool

The IP Fabric Reports Generator is designed with extensibility in mind. You can easily add new report types by creating new report classes and updating the configuration. To add a new report type:

1. Create a new config subclass in config.py with REPORT_TYPE, REPORT_NAME, and REPORT_DESCRIPTION set.
2. Create a new collector class if needed in data_collectors.py.
3. Create a new report class in report_types.py with config_class and collector_class set — it will be auto-registered.
4. Add a new template for the report in the templates directory.
5. (Optional) Add a new CSS style in the styles directory.
6. Update the documentation to include the new report type.

Contributing

We welcome contributions! Please see our Contributing Guidelines for more information on how to get started.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please open an issue on the GitHub repository or contact the maintainers directly.

---

The IP Fabric Reports Generator simplifies the process of creating detailed network reports, saving time and providing valuable insights into your network infrastructure. Whether you're conducting routine audits, troubleshooting issues, or maintaining documentation, this tool streamlines your workflow and enhances your network management capabilities.