codexlens 0.1.0__tar.gz

codexlens-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

codexlens-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Python 3.11 quality checks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Install locked dependencies
+        run: uv sync --all-groups --frozen
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Validate owned ExpenseFlow fixture
+        working-directory: examples/expenseflow
+        run: |
+          uv sync --all-groups --frozen
+          uv run pytest
+          uv run ruff check .
+
+      - name: Generate machine-readable static report
+        run: uv run codexlens scan src --format json > codexlens-report.json
+
+      - name: Upload static report
+        uses: actions/upload-artifact@v7
+        with:
+          name: codexlens-static-report
+          path: codexlens-report.json
+          if-no-files-found: error
+          retention-days: 7

codexlens-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  publish-github-release:
+    name: Build and publish GitHub Release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out release tag
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Install locked dependencies
+        run: uv sync --all-groups --frozen
+
+      - name: Verify quality
+        run: |
+          uv run ruff check .
+          uv run pytest
+
+      - name: Verify tag matches package version
+        shell: bash
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          package_version="$(uv run python -c "from importlib.metadata import version; print(version('codexlens'))")"
+          test "$tag_version" = "$package_version"
+
+      - name: Build distributions
+        run: uv build --out-dir dist
+
+      - name: Upload release artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: codexlens-${{ github.ref_name }}-distributions
+          path: dist/
+          if-no-files-found: error
+
+      - name: Create or update GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          if gh release view "$GITHUB_REF_NAME" > /dev/null 2>&1; then
+            gh release upload "$GITHUB_REF_NAME" dist/* --clobber
+          else
+            gh release create "$GITHUB_REF_NAME" dist/* \
+              --verify-tag \
+              --title "CodexLens $GITHUB_REF_NAME" \
+              --notes-file RELEASE_NOTES.md
+          fi

codexlens-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+build/
+dist/
+.env
+.env.*
+!.env.example

codexlens-0.1.0/BUILD_WEEK_DEMO_SCRIPT.md

@@ -0,0 +1,101 @@
+# CodexLens Build Week Demo Script
+
+Use this as a recording checklist, not as a claim that the offline replay is a
+live model run. Replace every bracketed placeholder with real submission
+details before publishing.
+
+## Preflight
+
+- [ ] Repository is public with the MIT license, or shared with the event's
+  required review addresses.
+- [ ] `uv sync --all-groups`, `uv run pytest`, and `uv run ruff check .` pass.
+- [ ] The live model account has access to the GPT-5.6 model selected for the
+  Build Week recording.
+- [ ] `OPENAI_API_KEY` is set locally and never shown in the video.
+- [ ] The `examples/expenseflow/work/` copy is freshly prepared.
+- [ ] The final Codex `/feedback` session ID for the core build is available.
+
+## Under-three-minute recording outline
+
+### 0:00–0:20 — Problem and product
+
+Say: “Traditional static checks can find obvious dangerous calls, but they do
+not reliably understand that an expense belongs to a tenant. CodexLens combines
+local checks, model-assisted business-logic review, and a confirmation-gated
+fix.”
+
+Show the README architecture diagram or run:
+
+```bash
+uv run codexlens demo
+```
+
+If using this command, say clearly: “This is an offline recorded replay for
+judges; it makes no API request.” Do not present it as the live GPT-5.6 result.
+
+### 0:20–0:45 — Establish the real vulnerable behavior
+
+From `examples/expenseflow/`:
+
+```bash
+uv run pytest tests/test_exploit_proof.py tests/test_hardened_reference.py
+```
+
+Explain that the first test proves a manager in tenant Acme can approve a
+Globex expense, while the hardened reference defines the correct invariant.
+
+### 0:45–1:55 — Live selected-model scan and review
+
+From the repository root, use the actual GPT-5.6 model ID available to the
+recording account:
+
+```powershell
+uv run python examples/expenseflow/scripts/prepare_demo.py
+$env:CODEXLENS_MODEL = "[your GPT-5.6 model ID]"
+uv run codexlens scan examples/expenseflow/work/app/main.py --fix
+```
+
+Narrate the evidence, not just the label: the route checks that the caller is a
+manager, then looks up an attacker-controlled expense ID without limiting it to
+the actor's tenant. Point out the AI finding is labeled for human review.
+
+Show the generated Rich diff. State that CodexLens produced the diff locally
+from a validated one-source-unit replacement. Review it, then explicitly press
+`y`; do not automate this input.
+
+### 1:55–2:20 — Verify the repaired behavior
+
+From `examples/expenseflow/`:
+
+```bash
+uv run pytest tests/test_live_patch.py
+```
+
+Explain that the request is now denied and the original expense stays
+unapproved. Show that `vulnerable/` was not changed; only the ignored disposable
+`work/` copy was eligible for the live patch.
+
+### 2:20–2:50 — Engineering and Codex use
+
+Show the JSON CI output or the workflow briefly:
+
+```bash
+uv run codexlens scan src --format json
+```
+
+Say only what is true for the final project. A safe, accurate framing is:
+“I used Codex as an implementation partner to design the constrained patch
+workflow, build the owned demo fixture, and add tests for confirmation, stale
+source, and JSON reporting. GPT-5.6 performs the live business-logic review and
+patch proposal in this recording.”
+
+## Submission copy checklist
+
+- [ ] Choose the Developer Tools category.
+- [ ] Include the project description, repository URL, setup commands, and
+  supported platform (Python 3.11+ on Windows, macOS, and Linux).
+- [ ] Link the public narrated video and keep it below the event time limit.
+- [ ] Explain that the no-key `codexlens demo` command is a recorded replay and
+  the ExpenseFlow fixture is intentionally vulnerable and non-deployable.
+- [ ] Highlight the live GPT-5.6 scan separately from the no-key replay.
+- [ ] Add the Codex `/feedback` session ID: `[paste session ID here]`.

codexlens-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to CodexLens are documented in this file.
+
+The project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-07-20
+
+### Added
+
+- Three-pass Python security-auditing pipeline: local static analysis,
+  model-assisted business-logic review, and confirmation-gated auto-fix.
+- Model-neutral OpenAI Responses API integration selected with `--model` or
+  `CODEXLENS_MODEL`.
+- Locally validated, single-source-unit patch proposals with an explicit
+  `y`/`n` decision and atomic application safeguards.
+- Source-free JSON reporting for CI and a GitHub Actions quality workflow.
+- An owned ExpenseFlow IDOR demonstration, exploit proof, hardened reference,
+  regression test, and credential-free offline replay.
+- `codexlens --version` for release verification and support workflows.
+
+### Security
+
+- Heuristic redaction before optional model-assisted analysis.
+- Strict local validation of model output and patch bindings before a file can
+  be changed.

codexlens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shreyash Chaurasia
+
+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.

codexlens-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: codexlens
+Version: 0.1.0
+Summary: AI-powered security auditing for Python projects.
+Project-URL: Homepage, https://github.com/ShreyashChaurasia/CodexLens
+Project-URL: Repository, https://github.com/ShreyashChaurasia/CodexLens
+Project-URL: Issues, https://github.com/ShreyashChaurasia/CodexLens/issues
+Project-URL: Changelog, https://github.com/ShreyashChaurasia/CodexLens/blob/main/CHANGELOG.md
+Author: Shreyash Chaurasia
+License: MIT License
+        
+        Copyright (c) 2026 Shreyash Chaurasia
+        
+        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.
+License-File: LICENSE
+Keywords: application-security,cli,openai,python,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: openai<3.0.0,>=1.0.0
+Requires-Dist: rich<15.0.0,>=13.7.0
+Requires-Dist: typer<1.0.0,>=0.15.0
+Description-Content-Type: text/markdown
+
+# CodexLens
+
+CodexLens is a Python CLI security auditor for projects that need more than
+pattern matching. It combines deterministic local checks with optional
+AI-assisted business-logic review, then presents constrained code fixes in a
+Rich terminal diff. A source file changes only after explicit confirmation.
+
+This repository provides a reproducible OpenAI Build Week demonstration of the
+complete workflow: static analysis, an AI review candidate, a confirmation-gated
+patch, and a security regression test.
+
+## Evaluation paths
+
+| Path | Credentials | Command | Outcome |
+| --- | --- | --- | --- |
+| Local static audit | None | `uv run codexlens scan src` | Pass 1 detection with no network request. |
+| Offline workflow replay | None | `uv run codexlens demo` | A deterministic Rich-terminal replay; no OpenAI request and no repository modification. |
+| Live end-to-end evaluation | OpenAI API key and model ID | [ExpenseFlow](examples/expenseflow/README.md) | A selected OpenAI model reviews and proposes a fix for the ExpenseFlow IDOR scenario. |
+
+The offline replay is prominently labelled **offline recorded replay**. It is a
+deterministic product walkthrough, not a substitute for a live model result.
+
+## Capabilities
+
+| Pass | Execution | Purpose | Output |
+| --- | --- | --- | --- |
+| 1. Static analysis | Local | Scans Python files with regex, entropy, and AST checks. | Confirmed findings, candidates, and diagnostics. |
+| 2. AI deep scan | Optional OpenAI Responses API request | Reviews bounded, redacted source units for business-logic weaknesses. | Structured findings that require human review. |
+| 3. Interactive auto-fix | Optional after completed Pass 2 | Proposes a narrowly scoped source-unit replacement. | A locally generated diff and an explicit `y`/`n` decision. |
+
+Pass 1 detects likely hardcoded credentials and high-entropy secret candidates,
+dynamic shell use, `shell=True`, `eval`/`exec`, unsafe pickle/YAML
+deserialization, dynamically constructed database queries, and disabled TLS
+verification. Pass 2 assesses broken object-level authorization (including
+IDOR), privilege escalation, mass assignment, and race conditions.
+
+AI findings are review candidates rather than confirmed vulnerabilities. The
+tool is a security-review aid, not a security guarantee.
+
+## Installation and local verification
+
+### Requirements
+
+- Python 3.11 or newer
+- [uv](https://docs.astral.sh/uv/)
+- An OpenAI API key only for Pass 2 and Pass 3
+
+At the repository root:
+
+```bash
+uv sync --all-groups
+uv run codexlens --help
+uv run codexlens scan src
+uv run codexlens demo
+```
+
+`scan src` runs Pass 1 only when no model is configured and makes no external
+request. `demo` stages a self-contained ExpenseFlow example in a temporary directory,
+replays schema-valid Pass 2 and Pass 3 responses through CodexLens' normal
+local validation path, presents the confirmation prompt, and discards the
+temporary source after completion.
+
+## Live AI scanning
+
+Live AI scanning requires an OpenAI API key and an accessible, text-capable
+model that supports the structured response format used by CodexLens. The
+model ID is supplied per live scan or through `CODEXLENS_MODEL`; CodexLens has
+no hard-coded model-family default or client-side model allowlist.
+
+PowerShell:
+
+```powershell
+$env:OPENAI_API_KEY = "<api-key>"
+$env:CODEXLENS_MODEL = "<model-id>"
+uv run codexlens scan ./my_project
+uv run codexlens scan ./my_project --model "another-model-id"
+```
+
+Bash or zsh:
+
+```bash
+export OPENAI_API_KEY="<api-key>"
+export CODEXLENS_MODEL="<model-id>"
+uv run codexlens scan ./my_project
+```
+
+The `--model` / `-m` value overrides `CODEXLENS_MODEL`. Without either value,
+CodexLens intentionally completes only local Pass 1. With a model configured,
+Pass 2 uses the OpenAI Responses API and Pass 3 makes a separate request only
+when `--fix` is present. Model capabilities can be confirmed through OpenAI's
+[model catalog](https://developers.openai.com/api/docs/models) and
+[Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs).
+
+> **Data-handling notice:** A live scan sends bounded source context to OpenAI,
+> and API usage is billed to the associated account. Known credentials,
+> sensitive assignments, and high-entropy literals are redacted heuristically
+> before submission, and API requests set `store=False`; these controls do not
+> guarantee removal of every sensitive detail. Live scanning is appropriate
+> only for code authorized for sharing with the selected service.
+
+## Interactive patch review
+
+A live Pass 3 run is requested with `--fix`:
+
+```bash
+uv run codexlens scan ./my_project --model "model-id" --fix
+```
+
+| Safeguard | Behavior |
+| --- | --- |
+| Eligibility | Only findings from a completed Pass 2 scan and bound to a reviewed Python source unit can reach Pass 3. |
+| Preview | CodexLens generates the unified diff locally after validating the replacement's target, scope, syntax, sensitive-content policy, bindings, and size. |
+| Confirmation | `y` is the only input that applies a proposal. `n`, Enter, missing input, or an interrupted prompt declines it. |
+| Application | A fresh file hash is checked before an atomic same-directory replacement. A run applies at most one validated patch. |
+
+Declining a proposal permits review of another eligible proposal. After an
+accepted patch, a new scan and the project's test suite provide the next
+verification step. CodexLens does not execute model-provided commands or trust
+model-provided file paths and diffs.
+
+## ExpenseFlow showcase
+
+[`examples/expenseflow/`](examples/expenseflow/README.md) is a self-contained,
+intentionally vulnerable multi-tenant FastAPI service with synthetic data. The
+primary scenario is a manager in one tenant approving an expense belonging to
+another tenant: a broken-object-authorization / IDOR flaw that a role check
+alone does not prevent.
+
+The baseline evidence is reproducible:
+
+```bash
+cd examples/expenseflow
+uv sync --all-groups
+uv run pytest tests/test_exploit_proof.py tests/test_hardened_reference.py
+```
+
+The exploit-proof test passes by demonstrating the vulnerable cross-tenant
+approval. The hardened-reference test documents the intended security property.
+The example README contains the isolated live-patch workflow and post-patch
+regression test. The fixture must not be deployed or reused outside this
+controlled demonstration.
+
+The [Build Week recording script](BUILD_WEEK_DEMO_SCRIPT.md) documents the
+exploit → live scan → reviewed diff → regression-test sequence and separates
+the no-key replay from the live selected-model demonstration.
+
+## CI, reports, and exit codes
+
+The Rich terminal UI is the default. `--format json` produces a stable,
+machine-readable report for CI and other tooling:
+
+```bash
+uv run codexlens scan src --format json > codexlens-report.json
+```
+
+The report schema is `codexlens.scan.v1`. It contains relative locations,
+finding metadata, diagnostics, pass status, and the exit code. It intentionally
+omits raw source, raw Responses API output, source-unit bindings, and patch
+diffs. Finding descriptions can still contain code-derived information, so the
+report should be handled as potentially sensitive.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | The requested scan completed with no confirmed static finding. |
+| `1` | The scan completed with one or more confirmed static findings. |
+| `3` | A requested scan or fix did not complete safely; the output contains a diagnostic. |
+
+AI review candidates do not independently fail CI. `--format json` and `--fix`
+cannot be combined because patch review requires the interactive Rich diff and
+explicit confirmation.
+
+The included [GitHub Actions workflow](.github/workflows/ci.yml) installs
+locked dependencies on Python 3.11, runs Ruff and pytest for both projects, and
+uploads the static JSON report as an artifact.
+
+## Scope and security posture
+
+- Pass 1 is local. Pass 2 and Pass 3 are opt-in and request `store=False`.
+- Static detection and redaction are narrow heuristics, not complete
+  vulnerability coverage or data-loss prevention.
+- CodexLens audits Python source files only. Incomplete static or AI coverage
+  produces diagnostics and exit code `3` instead of a silent success.
+- Scanned code and model output are treated as untrusted data. Human review,
+  tests, and normal deployment controls remain required.
+- The CLI targets Windows, macOS, and Linux shells; both PowerShell and POSIX
+  environment-variable syntax are documented above.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run ruff check .
+uv run pytest
+```
+
+## Project information
+
+- [Release history](https://github.com/ShreyashChaurasia/CodexLens/releases)
+- [Changelog](CHANGELOG.md)
+- [Security policy](SECURITY.md)
+
+CodexLens is released under the [MIT License](LICENSE).