openaudit 0.1.1
Offline-first security audit tool (secrets & config scanning) for local codebases.
License: MIT
Requires Python: >=3.9

<div align="center">

<img src="https://raw.githubusercontent.com/neuralforgeone/OpenAuditKit/main/assets/logo1.png" alt="OpenAuditKit Logo" width="200" height="auto" />

# OpenAuditKit

[![PyPI version](https://badge.fury.io/py/openaudit.svg)](https://badge.fury.io/py/openaudit)
[![Python Versions](https://img.shields.io/pypi/pyversions/openaudit.svg)](https://pypi.org/project/openaudit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Powered by NeuralForge](https://img.shields.io/badge/Powered%20by-NeuralForge.one-blue)](https://neuralforge.one)

**Next-Gen Security Audit Tool for Modern Codebases.**
*Powered by AI. Secure by Design. Offline First.*

[🌐 Website](https://neuralforge.one) • [📚 Documentation](https://github.com/neuralforgeone/OpenAuditKit) • [🐛 Report Bug](https://github.com/neuralforgeone/OpenAuditKit/issues)

</div>

---

## � What is OpenAuditKit?

**OpenAuditKit** is not just another linter. It's an intelligent security companion that lives in your terminal. Unlike traditional tools that drown you in false positives, OpenAuditKit combines robust pattern matching (Regex & Entropy) with **Context-Aware AI Agents** to understand *why* a piece of code might be dangerous.

Whether you are a solo developer or part of a large enterprise, OpenAuditKit helps you ship secure code faster.

## ✨ Key Features

| Feature | Description |
| :--- | :--- |
| **🕵️ Secret Scanning** | Detects API keys, tokens, and credentials with high-entropy validation. |
| **⚙️ Config Audit** | Discovers misconfigurations in `Dockerfile`, `.env`, `Kubernetes`, and more. |
| **🧠 AI Advisory** | **(New)** Integrated AI Agents explain vulnerabilities and suggest fixes. |
| **🏗️ Architecture Analysis** | AI agents analyze your project structure for design flaws. |
| **🛡️ Threat Modeling** | auto-generates STRIDE threat models based on your codebase. |
| **🔌 Integrations** | Native support for CI/CD pipelines (GitHub Actions, GitLab CI). |
| **📝 JSON Reporting** | Export findings for easy integration with dashboards like DefectDojo. |

## 🚀 Installation

Install simply via pip:

```bash
pip install openaudit
```

## ⚡ Quick Start

### 1. Basic Scan
Run a security scan on your current directory:

```bash
openaudit scan .
```

### 2. Enable AI Superpowers 🧠
Unlock the full potential with AI agents that analyze architecture and data flow:

```bash
# Set your OpenAI API Key
openaudit config set-key sk-your-api-key

# Run an AI-enhanced scan
openaudit scan . --ai
```

### 3. Ask Your Code
Don't understand a complex file? Let the **Explain Agent** break it down:

```bash
openaudit explain src/complex_logic.py
```

## 📊 Comparison

| Feature | OpenAuditKit | Gitleaks | TruffleHog |
| :--- | :---: | :---: | :---: |
| **Finding Secrets** | ✅ | ✅ | ✅ |
| **Config Analysis** | ✅ | ❌ | ❌ |
| **AI Context Analysis** | ✅ | ❌ | ❌ |
| **Architecture Review** | ✅ | ❌ | ❌ |
| **Offline Capabilities** | ✅ | ✅ | ❌* |

*\*TruffleHog often requires API connectivity for verification.*

## 🤖 CI/CD Integration

Secure your pipeline with zero effort. Add this to your `.github/workflows/security.yml`:

```yaml
name: Security Audit
on: [push, pull_request]

jobs:
  openaudit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - run: pip install openaudit
      - run: openaudit scan . --ci --fail-on high --ai
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} # Optional for AI features
```

## 🛡️ Security Philosophy

At **NeuralForge**, we believe security tools should be:
1.  **Silent but Deadly:** Only alert on real issues (Low False Positives).
2.  **Educational:** Don't just find bugs, explain them.
3.  **Private:** Your code never leaves your machine unless you explicitly opt-in to AI features (which are redacted by default).

## 🤝 Contributing

We love contributions! Please check out our [Contributing Guide](CONTRIBUTING.md) to get started.

---

<div align="center">
  <sub>Built with ❤️ by the <a href="https://neuralforge.one">NeuralForge</a> Team.</sub>
</div>