netbox-atlassian 0.1.0__tar.gz

netbox_atlassian-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: netbox-atlassian
+Version: 0.1.0
+Summary: NetBox plugin to display Jira issues and Confluence pages related to devices
+Author-email: sieteunoseis <jeremy.worden@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/sieteunoseis/netbox-atlassian
+Project-URL: Repository, https://github.com/sieteunoseis/netbox-atlassian
+Project-URL: Issues, https://github.com/sieteunoseis/netbox-atlassian/issues
+Keywords: netbox,jira,confluence,atlassian,plugin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# NetBox Atlassian Plugin
+
+Display Jira issues and Confluence pages related to devices in NetBox.
+
+## Features
+
+- **Device Tab** - Shows Jira issues and Confluence pages mentioning device attributes
+- **VM Tab** - Same functionality for Virtual Machines
+- **Configurable Search Fields** - Search by hostname, serial, asset tag, role, IP, etc.
+- **OR Search Logic** - Finds content matching any configured field
+- **On-Premise Support** - Works with Jira Server/Data Center and Confluence Server/Data Center
+- **Cloud Ready** - Prepared for Atlassian Cloud (future release)
+- **Caching** - Results cached to reduce API calls
+- **Project/Space Filtering** - Limit searches to specific Jira projects or Confluence spaces
+
+## Requirements
+
+- NetBox 4.0+
+- Python 3.10+
+- Access to Jira and/or Confluence REST APIs
+
+## Installation
+
+```bash
+pip install netbox-atlassian
+```
+
+Add to `configuration.py`:
+
+```python
+PLUGINS = [
+    "netbox_atlassian",
+]
+```
+
+## Configuration
+
+```python
+PLUGINS_CONFIG = {
+    "netbox_atlassian": {
+        # Jira settings (on-prem)
+        "jira_url": "https://jira.example.com",
+        "jira_username": "api_user",
+        "jira_password": "api_token_or_password",
+        "jira_verify_ssl": True,
+        "jira_projects": [],  # Empty = all projects
+
+        # Confluence settings (on-prem)
+        "confluence_url": "https://confluence.example.com",
+        "confluence_username": "api_user",
+        "confluence_password": "api_token_or_password",
+        "confluence_verify_ssl": True,
+        "confluence_spaces": [],  # Empty = all spaces
+
+        # Search configuration
+        "search_fields": [
+            {"name": "Hostname", "attribute": "name", "enabled": True},
+            {"name": "Serial", "attribute": "serial", "enabled": True},
+            {"name": "Asset Tag", "attribute": "asset_tag", "enabled": False},
+            {"name": "Role", "attribute": "role.name", "enabled": False},
+            {"name": "Primary IP", "attribute": "primary_ip4.address", "enabled": False},
+        ],
+
+        # Results limits
+        "jira_max_results": 10,
+        "confluence_max_results": 10,
+
+        # General
+        "timeout": 30,
+        "cache_timeout": 300,
+        "device_types": [],  # Filter by manufacturer (empty = all)
+    }
+}
+```
+
+## Search Fields
+
+The `search_fields` configuration defines which device attributes are searched. Searches use **OR logic** - content matching any enabled field will be returned.
+
+| Field | Attribute Path | Description |
+|-------|---------------|-------------|
+| Hostname | `name` | Device name |
+| Serial | `serial` | Serial number |
+| Asset Tag | `asset_tag` | Asset tag |
+| Role | `role.name` | Device role name |
+| Primary IP | `primary_ip4.address` | Primary IPv4 address |
+| Site | `site.name` | Site name |
+| Tenant | `tenant.name` | Tenant name |
+
+### Custom Fields
+
+You can search custom fields using dot notation:
+
+```python
+{"name": "CMDB ID", "attribute": "custom_field_data.cmdb_id", "enabled": True}
+```
+
+## Screenshots
+
+### Device Tab
+Shows Jira issues and Confluence pages in a split view:
+- Left: Jira issues with key, summary, status, and type
+- Right: Confluence pages with title, space, and breadcrumb
+
+### Settings Page
+View current configuration and test connections to Jira/Confluence.
+
+## API Endpoints
+
+The plugin adds these endpoints:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/plugins/atlassian/settings/` | GET | View settings |
+| `/plugins/atlassian/test-jira/` | POST | Test Jira connection |
+| `/plugins/atlassian/test-confluence/` | POST | Test Confluence connection |
+
+## Troubleshooting
+
+### Connection Errors
+
+1. Verify URLs are correct and accessible from NetBox server
+2. Check username/password or API token
+3. For on-prem, ensure `verify_ssl` matches your certificate setup
+4. Check firewall rules allow outbound HTTPS
+
+### No Results
+
+1. Verify search fields are enabled in configuration
+2. Check that Jira/Confluence content contains the device attributes
+3. Review project/space filters if configured
+4. Check API user has read permissions
+
+### Slow Performance
+
+1. Increase `cache_timeout` to reduce API calls
+2. Reduce `max_results` values
+3. Use project/space filters to limit search scope
+
+## Development
+
+```bash
+git clone https://github.com/sieteunoseis/netbox-atlassian.git
+cd netbox-atlassian
+pip install -e ".[dev]"
+
+# Run linting
+black netbox_atlassian/
+isort netbox_atlassian/
+flake8 netbox_atlassian/
+```
+
+## License
+
+Apache 2.0
+
+## Author
+
+sieteunoseis

netbox_atlassian-0.1.0/README.md

@@ -0,0 +1,159 @@
+# NetBox Atlassian Plugin
+
+Display Jira issues and Confluence pages related to devices in NetBox.
+
+## Features
+
+- **Device Tab** - Shows Jira issues and Confluence pages mentioning device attributes
+- **VM Tab** - Same functionality for Virtual Machines
+- **Configurable Search Fields** - Search by hostname, serial, asset tag, role, IP, etc.
+- **OR Search Logic** - Finds content matching any configured field
+- **On-Premise Support** - Works with Jira Server/Data Center and Confluence Server/Data Center
+- **Cloud Ready** - Prepared for Atlassian Cloud (future release)
+- **Caching** - Results cached to reduce API calls
+- **Project/Space Filtering** - Limit searches to specific Jira projects or Confluence spaces
+
+## Requirements
+
+- NetBox 4.0+
+- Python 3.10+
+- Access to Jira and/or Confluence REST APIs
+
+## Installation
+
+```bash
+pip install netbox-atlassian
+```
+
+Add to `configuration.py`:
+
+```python
+PLUGINS = [
+    "netbox_atlassian",
+]
+```
+
+## Configuration
+
+```python
+PLUGINS_CONFIG = {
+    "netbox_atlassian": {
+        # Jira settings (on-prem)
+        "jira_url": "https://jira.example.com",
+        "jira_username": "api_user",
+        "jira_password": "api_token_or_password",
+        "jira_verify_ssl": True,
+        "jira_projects": [],  # Empty = all projects
+
+        # Confluence settings (on-prem)
+        "confluence_url": "https://confluence.example.com",
+        "confluence_username": "api_user",
+        "confluence_password": "api_token_or_password",
+        "confluence_verify_ssl": True,
+        "confluence_spaces": [],  # Empty = all spaces
+
+        # Search configuration
+        "search_fields": [
+            {"name": "Hostname", "attribute": "name", "enabled": True},
+            {"name": "Serial", "attribute": "serial", "enabled": True},
+            {"name": "Asset Tag", "attribute": "asset_tag", "enabled": False},
+            {"name": "Role", "attribute": "role.name", "enabled": False},
+            {"name": "Primary IP", "attribute": "primary_ip4.address", "enabled": False},
+        ],
+
+        # Results limits
+        "jira_max_results": 10,
+        "confluence_max_results": 10,
+
+        # General
+        "timeout": 30,
+        "cache_timeout": 300,
+        "device_types": [],  # Filter by manufacturer (empty = all)
+    }
+}
+```
+
+## Search Fields
+
+The `search_fields` configuration defines which device attributes are searched. Searches use **OR logic** - content matching any enabled field will be returned.
+
+| Field | Attribute Path | Description |
+|-------|---------------|-------------|
+| Hostname | `name` | Device name |
+| Serial | `serial` | Serial number |
+| Asset Tag | `asset_tag` | Asset tag |
+| Role | `role.name` | Device role name |
+| Primary IP | `primary_ip4.address` | Primary IPv4 address |
+| Site | `site.name` | Site name |
+| Tenant | `tenant.name` | Tenant name |
+
+### Custom Fields
+
+You can search custom fields using dot notation:
+
+```python
+{"name": "CMDB ID", "attribute": "custom_field_data.cmdb_id", "enabled": True}
+```
+
+## Screenshots
+
+### Device Tab
+Shows Jira issues and Confluence pages in a split view:
+- Left: Jira issues with key, summary, status, and type
+- Right: Confluence pages with title, space, and breadcrumb
+
+### Settings Page
+View current configuration and test connections to Jira/Confluence.
+
+## API Endpoints
+
+The plugin adds these endpoints:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/plugins/atlassian/settings/` | GET | View settings |
+| `/plugins/atlassian/test-jira/` | POST | Test Jira connection |
+| `/plugins/atlassian/test-confluence/` | POST | Test Confluence connection |
+
+## Troubleshooting
+
+### Connection Errors
+
+1. Verify URLs are correct and accessible from NetBox server
+2. Check username/password or API token
+3. For on-prem, ensure `verify_ssl` matches your certificate setup
+4. Check firewall rules allow outbound HTTPS
+
+### No Results
+
+1. Verify search fields are enabled in configuration
+2. Check that Jira/Confluence content contains the device attributes
+3. Review project/space filters if configured
+4. Check API user has read permissions
+
+### Slow Performance
+
+1. Increase `cache_timeout` to reduce API calls
+2. Reduce `max_results` values
+3. Use project/space filters to limit search scope
+
+## Development
+
+```bash
+git clone https://github.com/sieteunoseis/netbox-atlassian.git
+cd netbox-atlassian
+pip install -e ".[dev]"
+
+# Run linting
+black netbox_atlassian/
+isort netbox_atlassian/
+flake8 netbox_atlassian/
+```
+
+## License
+
+Apache 2.0
+
+## Author
+
+sieteunoseis

netbox_atlassian-0.1.0/netbox_atlassian/__init__.py

@@ -0,0 +1,73 @@
+"""
+NetBox Atlassian Plugin
+
+Display Jira issues and Confluence pages related to devices in NetBox.
+Searches by configurable fields (hostname, serial, role, etc.) with OR logic.
+"""
+
+from netbox.plugins import PluginConfig
+
+__version__ = "0.1.0"
+
+
+class AtlassianConfig(PluginConfig):
+    """Plugin configuration for NetBox Atlassian integration."""
+
+    name = "netbox_atlassian"
+    verbose_name = "Atlassian"
+    description = "Display Jira issues and Confluence pages related to devices"
+    version = __version__
+    author = "sieteunoseis"
+    author_email = "sieteunoseis@github.com"
+    base_url = "atlassian"
+    min_version = "4.0.0"
+
+    # Required settings - plugin won't load without these
+    required_settings = []
+
+    # Default configuration values
+    default_settings = {
+        # Jira settings (on-prem)
+        "jira_url": "",  # e.g., "https://jira.example.com"
+        "jira_username": "",
+        "jira_password": "",  # or API token
+        "jira_verify_ssl": True,
+        # Confluence settings (on-prem)
+        "confluence_url": "",  # e.g., "https://confluence.example.com"
+        "confluence_username": "",
+        "confluence_password": "",  # or API token
+        "confluence_token": "",  # Personal Access Token (PAT) - preferred for on-prem
+        "confluence_verify_ssl": True,
+        # Cloud settings (for future use)
+        "use_cloud": False,
+        "cloud_api_token": "",
+        "cloud_email": "",
+        # Search configuration
+        # Fields to search - values are device attribute paths
+        # Searches use OR logic - matches any field
+        "search_fields": [
+            {"name": "Hostname", "attribute": "name", "enabled": True},
+            {"name": "Serial", "attribute": "serial", "enabled": True},
+            {"name": "Asset Tag", "attribute": "asset_tag", "enabled": False},
+            {"name": "Role", "attribute": "role.name", "enabled": False},
+            {"name": "Primary IP", "attribute": "primary_ip4.address", "enabled": False},
+        ],
+        # Jira search settings
+        "jira_max_results": 10,
+        "jira_projects": [],  # Empty = search all projects
+        "jira_issue_types": [],  # Empty = all types
+        # Confluence search settings
+        "confluence_max_results": 10,
+        "confluence_spaces": [],  # Empty = search all spaces
+        # General settings
+        "timeout": 30,
+        "cache_timeout": 300,  # Cache results for 5 minutes
+        # Enable legacy SSL renegotiation for older servers (required for OHSU wiki)
+        "enable_legacy_ssl": False,
+        # Device type filtering (like catalyst-center)
+        # Empty list = show tab for all devices
+        "device_types": [],  # e.g., ["cisco", "juniper"]
+    }
+
+
+config = AtlassianConfig