Metadata-Version: 2.4
Name: auditly
Version: 0.1.4
Summary: Auditly is a next-generation Python dependency vulnerability scanner with an integrated Requirements Generator that detects installed packages and creates requirements.txt files for secure, portable, and production-ready projects.
Home-page: https://github.com/krishnatadi/auditly-pypi
Author: Krishna Tadi
License: MIT
Keywords: python,security,dependency-scanner,vulnerability-scanner,requirements-generator,requirements.txt,package-audit,cybersecurity,devsecops,python-packages,dependency-management,open-source-security,package-scanner,pip,cli-tool,auditly
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32.5
Requires-Dist: tqdm>=4.67.3
Requires-Dist: packaging>=25.0
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

![PyPI Version](https://img.shields.io/pypi/v/auditly.svg)
![PyPI - License](https://img.shields.io/pypi/l/auditly)


# Auditly

**Auditly** is a modern, developer-friendly **Python dependency security and dependency-analysis CLI tool** that helps teams **identify vulnerabilities, risky versions, and dependency issues early** — before they reach production.

Auditly focuses on **clarity, speed, and actionable output**, making security **understandable and fixable** for developers.

---

## Why Auditly?

Most dependency scanners stop at direct dependencies.  
Auditly goes deeper.

- Simple CLI, zero configuration
- Scans installed environments & `requirements.txt`
- Optional **transitive dependency scanning**
- **Dependency tree visualization**
- Highlights vulnerable & risky package versions
- Shows fix suggestions when available
- JSON output for CI/CD pipelines
- Enterprise-ready foundation
- Identifies the package and version
- Displays the package description and metadata

---

## Features

| Feature | Description | Availability |
|---------|-------------|-------------|
| **Direct dependency scan** | Scans all installed packages or packages in a `requirements.txt` file | Yes | 
| **Fix suggestions** | Shows exact `pip install <package>==<version>` commands to fix vulnerabilities | Yes |
| **Summary stats** | Displays total packages scanned and total vulnerabilities | Yes |
| **Optional transitive scan** | Scans all sub-dependencies recursively (use `--transitive`) | Yes |
| **JSON output** | Pretty JSON output for CI/CD pipelines (use `--json`) | Yes |
| **Requirements.txt scan** | Scan packages listed in a requirements file | Yes |
| **Dependency tree visualization** | Visualize the dependency hierarchy of your project | Yes |
| **Explain Feature** | Get complete information about package `auditly explain <package name>` | Yes |
| **Requirements generator** | Auto-detect and generate requirements.txt from installed packages (use `generate`) | Yes |
---

## Package Details

| **Detail**              | **Description**                                                                 |
|-------------------------|---------------------------------------------------------------------------------|
| **Package Name**        | `auditly`                                                                       |
| **Version**             | `0.1.4`                                                                        |
| **Author**              | Krishna Tadi                                                                   |
| **Description**         | Auditly is a next-generation Python dependency vulnerability scanner.          |
| **License**             | MIT                                                                            |
| **Python Version**      | >= 3.7                                                                         |
| **Source Code**         | [GitHub Repository](https://github.com/krishnatadi/auditly-pypi)               |
| **Bug Tracker**         | [GitHub Issues](https://github.com/krishnatadi/auditly-pypi/issues)            |
| **PyPI**                | [Auditly on PyPI](https://pypi.org/project/auditly)                            |

---

## Installation

To install Auditly, use the following command:

```bash
pip install auditly
```

Ensure you have Python 3.7 or higher installed. You can download Python from [python.org](https://www.python.org/downloads/).

---

## Usage

Auditly can be run as a CLI tool. Below is a summary of all available commands and flags.

| Command | Description |
|--------|-------------|
| `auditly` | Scan installed Python environment |
| `auditly --transitive` | Scan environment including sub-dependencies |
| `auditly -r requirements.txt` | Scan dependencies from a requirements file |
| `auditly -r requirements.txt --transitive` | Scan requirements including transitive dependencies |
| `auditly --json` | Output results in JSON format |
| `auditly --insecure` | Disable SSL verification (for enterprise networks) |
| `auditly pkg --tree` | Show dependency tree for entire environment |
| `auditly pkg <package>==<version> --tree` | Show dependency tree for a specific package version |
| `auditly explain requests` | Explain an installed package |
| `auditly explain requests==2.32.5` | Explain a specific version |
| `auditly explain flask==0.12` | Explain a known vulnerable package |
| `auditly generate` | Detect all installed packages and generate requirements.txt |

---

## Examples
### 1. Default scan of installed environment

```bash
auditly
```

**Output:**

```text
[auditly] Vulnerability Scan Summary
Total Packages Scanned      : 10
Total Vulnerabilities Found : 2

Package     : flask==0.12
Risk Score  : 10
  - CVE-2018-1000656: Flask <0.12.3 XSS
    → Suggested fix: pip install flask==0.12.3
------------------------------------------------------------
Package     : somepkg==1.0
Risk Score  : 7
  - CVE-XXXX-YYYY: Some vulnerability
    → No fix available. Try contacting package developers
------------------------------------------------------------
```

### 2. Scan `requirements.txt`

```bash
auditly -r requirements.txt
```
---

### 3. Deep / Transitive Scan (Sub-dependencies)

```bash
auditly --transitive
```

Scans all installed packages including their sub-dependencies.

Alerts for deprecated / EOL packages.

Progress bar shows scan progress.

---

### 4. JSON Output (CI/CD pipelines)

```bash
auditly --json
```

**Output:**

```json
{
    "summary": {
        "total_packages_scanned": 10,
        "total_vulnerabilities_found": 2
    },
    "results": [
        {
            "package": "flask",
            "version": "0.12",
            "risk_score": 10,
            "vulnerabilities": [
                {
                    "id": "CVE-2018-1000656",
                    "summary": "Flask <0.12.3 XSS",
                    "fix_version": "0.12.3",
                    "references": [
                        "https://nvd.nist.gov/vuln/detail/CVE-2018-1000656"
                        ]
                }
            ]
        }
    ]
}
```

---
## Dependency Tree Feature

Auditly includes a powerful **Dependency Tree Visualization** feature that allows you to view the entire dependency hierarchy of your Python project. This feature is particularly useful for identifying transitive dependencies and understanding how packages are interconnected.

### Commands for Dependency Tree

| **Command / Flag**              | **Description**                                                                 | **Example**                          |
|---------------------------------|---------------------------------------------------------------------------------|--------------------------------------|
| `auditly pkg requests==<version> --tree` | Displays the dependency tree for a specific package and version               | `auditly pkg requests==2.31.0 --tree`|
| `auditly pkg --tree`            | Displays the dependency tree for all packages in the installed environment      | `auditly pkg --tree`                 |

### Example Output

```bash
auditly pkg --tree
```

**Output:**

```text
[auditly] Dependency Tree

flask==2.0.3
├── Werkzeug>=2.0
├── Jinja2>=3.0
│   └── MarkupSafe>=2.0
└── itsdangerous>=2.0

requests==2.31.0
└── urllib3>=1.26.5
```

This output shows the top-level dependencies and their sub-dependencies, making it easy to identify potential issues or vulnerabilities in the dependency chain.

---

## Requirements Generator Feature

Auditly includes a powerful **Requirements Generator** feature that automatically detects all installed Python packages from your environment and generates a `requirements.txt` file. This is especially useful for:

- **Moving projects to production** without manual dependency tracking
- **Sharing projects** with other teams with exact package versions
- **Creating a baseline** requirements file from an existing environment
- **Simplifying setup** and ensuring reproducible environments

### Key Benefits

**Automatic Detection** - Finds all packages in your environment (virtual or global)  
**Accurate Versions** - Captures exact package versions with `package==version` format  
**Prevents Conflicts** - Won't overwrite existing `requirements.txt` files (prevents accidental data loss)  
**CI/CD Ready** - Works seamlessly in automated pipelines  
**Safe & Reliable** - Clear error messages guide you on next steps

### Commands for Requirements Generator

| **Command / Flag**              | **Description**                                                                 |
|---------------------------------|---------------------------------------------------------------------------------|
| `auditly generate` | Detect all installed packages and generate requirements.txt |

### How to Use

#### Step 1: Generate requirements.txt

```bash
auditly generate
```

**Output:**

```text
[auditly] Detecting installed packages...
[auditly] Found 45 package(s). Generating requirements.txt...

[auditly] Requirements file generated successfully!
  Location: /path/to/requirements.txt
  Packages: 45

Next steps:
  - Review the generated file: cat requirements.txt
  - Share with your team or move to production
  - For future scans, use: auditly -r requirements.txt
```

#### Step 2: Review the generated requirements.txt

```bash
cat requirements.txt
```

**Sample Output:**

```text
certifi==2024.11.26
charset-normalizer==3.3.2
idna==3.10
packaging==25.0.1
pip==25.0
requests==2.32.5
tqdm==4.67.3
urllib3==2.1.0
setuptools==69.0.3
wheel==0.42.0
...
```

#### Step 3: Share or Deploy

```bash
# Copy to a repository
git add requirements.txt
git commit -m "Add auto-generated requirements.txt"

# Or use it for production setup
pip install -r requirements.txt
```

### Error Handling

If `requirements.txt` already exists, Auditly will throw an error to prevent accidental data loss:

```text
[auditly] ERROR: 'requirements.txt' already exists.

To avoid conflicts and duplicate entries, auditly will not overwrite existing files.

Please choose one of the following options:
  1. Rename the existing file:
     - mv requirements.txt requirements.old.txt
  2. Review and update it manually before running the command again
  3. Delete it if you want to generate a fresh requirements.txt from the current environment

This approach ensures no data loss and helps you maintain consistency.
```

**Resolution:**

```bash
# Option 1: Backup and regenerate
mv requirements.txt requirements.backup.txt
auditly generate

# Option 2: Manually merge/update
# Edit requirements.txt as needed, then:
auditly generate  # Will now work

# Option 3: Use it as-is
auditly -r requirements.txt  # Scan the existing file
```

---

## Enterprise Networks & SSL Configuration

If you're running Auditly in an enterprise environment with SSL inspection, proxies, or custom certificate authorities, you may encounter SSL certificate verification errors. Auditly provides several ways to handle this:

### Option 1: Use the `--insecure` flag (Quick Fix)

```bash
auditly --insecure
auditly -r requirements.txt --insecure
```

**Note:** This disables SSL certificate verification. Only use this on networks you trust.

### Option 2: Use Custom Certificate Authority (Recommended)

If your enterprise uses a custom CA, export the certificate and set the environment variable:

```bash
# On Windows (PowerShell)
$env:REQUESTS_CA_BUNDLE = "C:\path\to\ca-bundle.crt"
auditly

# On Linux/macOS
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt
auditly
```

### Option 3: Permanently Disable SSL Verification (Last Resort)

```bash
# On Windows (PowerShell)
$env:AUDITLY_VERIFY_SSL = "false"
auditly

# On Linux/macOS
export AUDITLY_VERIFY_SSL=false
auditly
```

### Option 4: Use System Certificates (Best Practice)

Import your enterprise CA into the system certificate store:

- **Windows**: Import the `.crt` or `.pem` file into the Windows Certificate Store
- **Linux**: Add the certificate to `/etc/ssl/certs/` and run `update-ca-certificates`
- **macOS**: Add the certificate to the Keychain with `security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt`

---

## Discussions
- **GitHub Discussions**: Share use cases, report bugs, and suggest features.

We'd love to hear from you and see how you're using **Auditly** in your projects!

---

## Requesting Features
If you have an idea for a new feature, please open a feature request in the Issues section with:
- A clear description of the feature
- Why it would be useful

---

## Issues and Feedback
For issues, feedback, and feature requests, please open an issue on our [GitHub Issues page](http://github.com/krishnatadi/auditly-pypi/issues). We actively monitor and respond to community feedback.

---


## License

This project is licensed under the MIT License. See the [LICENSE](https://github.com/Krishnatadi/auditly-pypi/blob/main/LICENSE) file for details.
