Metadata-Version: 2.1
Name: nucleus-security-api-wrapper
Version: 0.1.0
Summary: Unofficial Python SDK for the Nucleus Security API - A third-party implementation
Home-page: https://github.com/nucleus/nucleus-python-sdk
Author: Nucleus SDK Team
Author-email: Loc Mai <jobs@locm.ai>
License: MIT License
        
        Copyright (c) 2024 Nucleus SDK Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/locm-ai/Nucleus-Security-Python-API-Wrapper
Project-URL: Documentation, https://github.com/locm-ai/Nucleus-Security-Python-API-Wrapper#readme
Project-URL: Repository, https://github.com/locm-ai/Nucleus-Security-Python-API-Wrapper.git
Project-URL: Issues, https://github.com/locm-ai/Nucleus-Security-Python-API-Wrapper/issues
Project-URL: Nucleus Security, https://nucleussec.com
Keywords: nucleus,security,api,sdk,vulnerability management,third-party,unofficial,api wrapper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# 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](https://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

```bash
pip install nucleus-security-api-wrapper
```

## Quick Start

### Synchronous Usage

```python
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

```python
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:
```bash
pip install jupyter
```

2. Navigate to the examples directory and start Jupyter:
```bash
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:

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

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

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

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

```python
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](https://api-docs.nucleussec.com/nucleus/docs/).

## 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 (jobs@locm.ai)

## License

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