nucleus-security-api-wrapper 0.1.0

Unofficial Python SDK for the Nucleus Security API - A third-party implementation

Unofficial Nucleus Security Python API Wrapper

This is an unofficial third-party Python SDK for interacting with the Nucleus Security API. This SDK provides a simple and intuitive interface to access Nucleus Security's vulnerability management platform, with support for both synchronous and asynchronous operations.

Note: This is not an official Nucleus Security product. This SDK is maintained by Loc Mai and is not affiliated with, officially maintained, or endorsed by Nucleus Security. For official Nucleus Security products, please visit nucleussec.com.

Features

• Full support for Nucleus Security API endpoints
• Async support for high-performance operations
• Built-in caching to reduce API calls
• Rate limiting to prevent API throttling
• Comprehensive error handling
• Type hints and data validation using Pydantic
• Detailed logging for debugging
• Retry mechanism with exponential backoff
• Interactive Jupyter notebook tutorial

Installation

pip install nucleus-security-api-wrapper

Quick Start

Synchronous Usage

from nucleus import NucleusClient
from nucleus.models import Severity, AssetType

# Initialize the client
client = NucleusClient(api_key="your-api-key")

# Get list of projects
projects = client.get_projects()

# Get specific project
project = client.get_project(project_id=123)

# Get assets in a project
assets = client.get_project_assets(project_id=123)

Asynchronous Usage

import asyncio
from nucleus.async_client import AsyncNucleusClient

async def main():
    async with AsyncNucleusClient(api_key="your-api-key") as client:
        # Fetch multiple resources concurrently
        projects, findings = await asyncio.gather(
            client.get_projects(),
            client.search_findings(
                project_id=123,
                filters=[{
                    "property": "finding_severity",
                    "value": "Critical",
                    "exact_match": True
                }]
            )
        )

asyncio.run(main())

Interactive Tutorial

We provide a Jupyter notebook tutorial that walks you through all the features of the SDK. To use it:

1. Install Jupyter if you haven't already:

pip install jupyter

2. Navigate to the examples directory and start Jupyter:

cd examples
jupyter notebook

3. Open nucleus_sdk_tutorial.ipynb in your browser

The tutorial covers:

• Basic SDK operations
• Working with projects, assets, and findings
• Async operations for improved performance
• Bulk operations and parallel processing
• Error handling and best practices
• Real-world usage examples

Advanced Features

Caching

The SDK includes built-in caching to reduce API calls:

from nucleus.async_client import AsyncNucleusClient

async with AsyncNucleusClient(
    api_key="your-api-key",
    cache_ttl=300  # Cache TTL in seconds
) as client:
    # First call hits the API
    projects = await client.get_projects()
    
    # Second call uses cached data
    projects_cached = await client.get_projects()

Rate Limiting

Built-in rate limiting prevents API throttling:

from nucleus.async_client import AsyncNucleusClient

async with AsyncNucleusClient(
    api_key="your-api-key",
    rate_limit_calls=100,  # Number of calls allowed
    rate_limit_period=60   # Period in seconds
) as client:
    # SDK automatically handles rate limiting
    for i in range(200):
        await client.get_projects()  # Will pause if rate limit is reached

Logging

Enable detailed logging for debugging:

import logging
from nucleus.utils import logger

# Set logging level
logger.setLevel(logging.DEBUG)

# Add custom handler if needed
handler = logging.StreamHandler()
handler.setFormatter(logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s'))
logger.addHandler(handler)

Error Handling

Comprehensive error handling with custom exceptions:

from nucleus import NucleusClient
from nucleus.exceptions import (
    NucleusAPIError,
    NucleusAuthError,
    NucleusNotFoundError,
    NucleusPermissionError
)

client = NucleusClient(api_key="your-api-key")

try:
    project = client.get_project(project_id=999999)
except NucleusNotFoundError:
    print("Project not found")
except NucleusAuthError:
    print("Authentication failed")
except NucleusPermissionError:
    print("Permission denied")
except NucleusAPIError as e:
    print(f"API error: {e}")

Bulk Operations

Efficiently handle multiple operations:

async with AsyncNucleusClient(api_key="your-api-key") as client:
    # Bulk update findings
    updates = [
        {
            "finding_number": "VULN-001",
            "finding_status": "In Progress",
            "comment": "Working on fix"
        },
        {
            "finding_number": "VULN-002",
            "finding_status": "In Progress",
            "comment": "Under review"
        }
    ]
    
    result = await client.bulk_update_findings(project_id, updates)

Examples

The SDK comes with several examples:

• examples/basic_usage.py: Basic synchronous operations
• examples/advanced_usage.py: Advanced features including async operations
• examples/nucleus_sdk_tutorial.ipynb: Interactive Jupyter notebook tutorial

API Documentation

For official API documentation, please visit the Nucleus Security API Documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Disclaimer

This is a third-party implementation and is not officially supported by Nucleus Security. Use at your own risk. While we strive to maintain compatibility with the Nucleus Security API, we cannot guarantee immediate updates when the API changes.

Author

Maintained by Loc Mai ([e-mail])

License

This SDK is released under the MIT License. See the LICENSE file for details.