AI Explain domain

.gitignore

@@ -1,2 +1,165 @@
-/openaudit/__pycache__
-*.pyc
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   with no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary dependencies to ensure reproducible builds.
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and others
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs
+.idea/
+.vscode/
+
+# OpenAuditKit local configs
+.openaudit_consent
+.openaudit_config.yaml
+report.json
+test.env
+/dist
+
+# Misc
+.DS_Store
+memory_bank.md

AI_ETHICS.md

@@ -0,0 +1,28 @@
+# 🛡 AI Ethics & Privacy in OpenAuditKit
+
+OpenAuditKit integrates AI capabilities with a "Safety-First" approach. We believe security tools should not compromise the privacy of the code they analyze.
+
+## 1. Opt-In by Default
+AI features are **strictly opt-in**.
+- You must explicitly pass the `--ai` flag to enable them.
+- On the first run, you will be asked to grant consent interactively.
+- For CI/CD, you must explicitly enable consent (e.g., via `openaudit consent --grant`).
+
+## 2. Data Redaction
+Before any code snippet is sent to an LLM (Large Language Model):
+- **Secrets are Redacted**: We use our static analysis engine to detect and mask secrets (API keys, passwords, tokens) with `[REDACTED]`.
+- **Anonymization**: We aim to strip PII where possible, though code context is preserved for analysis.
+
+## 3. Advisory Nature
+AI is non-deterministic.
+- All AI-generated findings are tagged as **Advisory**.
+- They should be reviewed by a human.
+- They do not block builds by default unless configured otherwise.
+
+## 4. Local vs External
+- We support local LLMs (e.g., via Ollama) for users who want zero data egress.
+- External providers (e.g., OpenAI, Anthropic) are optional and require your own API keys. We do not proxy your code through our servers.
+
+## 5. Transparency
+- We explain *why* an AI finding was generated.
+- We show the prompt context (in debug mode) so you know exactly what was sent.

README.md

@@ -7,7 +7,56 @@ OpenAuditKit is an open-source CLI security audit tool designed to scan your cod
 - **Config Scanning**: Identifies misconfigurations in deployment files (e.g., .env, Dockerfile).
 - **Secure**: Secrets are masked in outputs; offline-first design.
 - **Backend Ready**: Feature-based architecture with Pydantic models for easy integration into dashboards or APIs.
-- **Customizable**: Add your own rules! See [Rule Documentation](rules/README.md).
+- **Customizable**: Add your own rules! See [Rule Documentation](openopenaudit/rules/README.md).
+
+## 🛡️ Why OpenAuditKit?
+
+
+## 🎥 Usage Demo
+
+![OpenAuditKit Demo](path/to/demo.gif)
+*(Replace this with your actual usage GIF)*
+
+## Usage
+
+### Basic Scan
+```bash
+openaudit scan .
+```
+
+### 🧠 AI-Powered Analysis
+Unlock advanced capabilities by configuring your OpenAI API key:
+
+```bash
+# 1. Configure API Key
+openaudit config set-key sk-your-key-here
+
+# 2. Run Scan with AI Agents
+openaudit scan . --ai
+
+# 3. Explain a specific file
+openaudit explain openaudit/main.py
+```
+
+**AI Agents:**
+- **Architecture Agent**: Reviews modularity and dependencies.
+- **Cross-File Agent**: Traces dangerous data flows across modules.
+- **Explain Agent**: Provides detailed code explanations.
+- **Secret Agent**: Validates if found secrets are likely real or test data.
+- **Threat Model Agent**: Generates a STRIDE threat model for your project structure.
+
+### JSON Output
+```bash
+openaudit scan . --format json --output report.json
+```
+
+## 🛠 Features
+
+- **Secret Scanning**: Detects API keys and secrets using regex and entropy checks.
+- **Config Scanning**: Identifies misconfigurations in deployment files (e.g., .env, Dockerfile).
+- **Secure**: Secrets are masked in outputs; offline-first design (unless AI is enabled).
+- **Backend Ready**: Feature-based architecture with Pydantic models for easy integration into dashboards or APIs.
+- **Customizable**: Add your own rules! See [Rule Documentation](openaudit/rules/README.md).
 
 ## 🛡️ Why OpenAuditKit?
 
@@ -18,49 +67,27 @@ Often, security tools are either too simple (grep) or too complex (enterprise SA
 | **Secret Scanning** | ✅ | ✅ | ✅ |
 | **Config Scanning** | ✅ | ❌ | ❌ |
 | **Offline First** | ✅ | ✅ | ❌ (Often requires API) |
+| **AI Analysis** | ✅ (Optional) | ❌ | ❌ |
 | **Custom Rules** | ✅ (YAML) | ✅ (TOML) | ✅ (Detectors) |
 | **Backend Integration** | ✅ (Pydantic Models) | ❌ | ❌ |
-| **Configuration Check** | ✅ (.env, Docker) | ❌ | ❌ |
 
 ### Security Philosophy
-1. **Offline First**: No data leaves your machine. Your code is yours.
+1. **Offline First**: No data leaves your machine unless you explicitly enable AI features.
 2. **Confidence > Noise**: We use entropy checks and specific regexes to minimize false positives.
 3. **Actionable**: Every finding comes with a remediation step.
 
 ## Installation
+
 ```bash
-# From PyPI (Coming Real Soon!)
+# From PyPI
 pip install openaudit
 
-# Or from source
-git clone https://github.com/StartUp-Agency/OpenAuditKit.git
+# From Source
+git clone https://github.com/neuralforgeone/OpenAuditKit.git
 cd OpenAuditKit
 pip install .
 ```
 
-## Usage
-```bash
-# Basic Scan
-python -m openaudit.main .
-
-# With specific rules
-python -m openaudit.main . --rules-path ./my-rules
-
-# JSON Output
-python -m openaudit.main . --format json --output report.json
-```
-
-**Ignoring Files:**
-Create a `.oaignore` or `.openauditignore` file in your root directory to exclude files/folders from the scan (uses .gitignore syntax).
-
-Example `.oaignore`:
-```text
-node_modules/
-dist/
-tests/
-*.log
-```
-
 ## 🚀 CI/CD Integration
 
 OpenAuditKit is designed to run in CI/CD pipelines. Use the `--ci` flag to enable CI mode (exit code 1 on failure, no interactive elements).
@@ -82,7 +109,7 @@ jobs:
       with:
         python-version: '3.10'
     - run: pip install openaudit
-    - run: openaudit . --ci --fail-on high
+    - run: openaudit scan . --ci --fail-on high
 ```
 
 ### Exit Codes
@@ -93,7 +120,8 @@ jobs:
 
 Run the test suite with coverage:
 ```bash
-python -m pytest tests --cov=openaudit
+pip install -e .[dev]
+pytest tests --cov=openaudit
 ```
 
 We enforce a 90% test coverage threshold.

build/lib/openaudit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

build/lib/openaudit/main.py

@@ -0,0 +1,9 @@
+from openaudit.interface.cli.app import app
+
+import sys
+def main():
+    print(f"DEBUG: sys.argv = {sys.argv}")
+    app()
+
+if __name__ == "__main__":
+    main()