Metadata-Version: 2.4
Name: ipfreports
Version: 2.5.4
Summary: A package to generate reports from IP Fabric data
Project-URL: Homepage, https://www.ipfabric.io
Project-URL: Repository, https://gitlab.com/ip-fabric/integrations/ipfreports
Project-URL: Documentation, https://gitlab.com/ip-fabric/integrations/ipfreports#readme
Project-URL: Issues, https://support.ipfabric.io
Author-email: Milan Zapletal <milan.zapletal@ipfabric.io>
License-Expression: MIT
License-File: LICENSE
Keywords: documentation,ipfabric,lld,network,pdf,reports
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: <4.0,>=3.11
Requires-Dist: ipfabric>=7.10.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: netwlens>=1.3.1
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: requests>=2.0.0
Requires-Dist: setuptools>=65.0.0
Requires-Dist: weasyprint>=60.1
Description-Content-Type: text/markdown

# IP Fabric Reports Generator

[![PyPI version](https://img.shields.io/pypi/v/ipfreports.svg)](https://pypi.org/project/ipfreports/)

## 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:

```bash
ipfreports --list
```

This will output:

```text
  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:

```bash
pip install ipfreports
# or
uv pip install ipfreports
```

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

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

For local development:

```bash
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:**

```bash
# 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](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](https://gitlab.com/ip-fabric/integrations/ipfreports/-/releases)
— 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](#web-ui-docker)). 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:

```text
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:

   ```bash
   uv run ipfreports --list
   ```

2. Generate a specific report:

   ```bash
   uv run ipfreports --type management-protocol
   ```

   or

   ```bash
   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:

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

4. Specify a custom .env file:

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

5. Specify a custom CSS style:

   ```bash
   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):

   ```bash
   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:

```python
from ipfreports import IPFabricReportGenerator

generator = IPFabricReportGenerator()
generator.generate_report()
```

Or with specific options:

```python
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](ipfreports/styles/README.md).

## 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.
