codex-plugin-scanner 1.0.0__tar.gz

codex_plugin_scanner-1.0.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @hashgraph-online/core

codex_plugin_scanner-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/
+      - run: ruff format --check src/
+      - run: pytest --tb=short

codex_plugin_scanner-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,81 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish_target:
+        description: "Target repository"
+        required: true
+        default: testpypi
+        type: choice
+        options:
+          - testpypi
+          - pypi
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: codex-plugin-scanner-publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build + Verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+      - name: Build package
+        run: python -m build
+      - name: Verify distributions
+        run: twine check dist/*
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event.inputs.publish_target == 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event.inputs.publish_target != 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

codex_plugin_scanner-1.0.0/.github/workflows/scorecard.yml

@@ -0,0 +1,26 @@
+name: OpenSSF Scorecard
+on:
+  schedule:
+    - cron: '0 0 * * 0'
+  push:
+    branches: [main]
+permissions:
+  contents: read
+  id-token: write
+  security-events: write
+jobs:
+  scorecard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: ossf/scorecard-action@v2
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
+        if: always()

codex_plugin_scanner-1.0.0/.gitignore

@@ -0,0 +1,42 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+coverage/
+
+# Tooling
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*
+!.env.example

codex_plugin_scanner-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to Codex Plugin Scanner
+
+Thank you for your interest in contributing!
+
+## Development Setup
+
+```bash
+git clone https://github.com/hashgraph-online/codex-plugin-scanner.git
+cd codex-plugin-scanner
+pip install -e ".[dev]"
+pytest
+```
+
+## Adding New Checks
+
+1. Create a new check function in the appropriate file under `src/codex_plugin_scanner/checks/`.
+2. Add it to the corresponding `run_*_checks()` function.
+3. Write tests in `tests/`.
+4. Update the README's checks table.
+5. Submit a PR.
+
+## Code Style
+
+- Python 3.10+
+- Ruff for linting and formatting
+- All checks must return a `CheckResult` with accurate point values
+
+## Pull Request Process
+
+1. Fork the repo
+2. Create a feature branch
+3. Write tests for new functionality
+4. Ensure `pytest` passes and `ruff check` is clean
+5. Submit PR against `main`
+
+## License
+
+By contributing, you agree that your contributions will be licensed under Apache-2.0.

codex_plugin_scanner-1.0.0/LICENSE

@@ -0,0 +1,118 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form.
+
+      "Derivative Works" shall mean any work that is based on the Work
+      and for which the editorial revisions, annotations, elaborations,
+      or other modifications represent, as a whole, an original work of
+      authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law, Contributor be liable for any
+      damages, including any direct, indirect, special, incidental, or
+      consequential damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Hashgraph Online
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0

codex_plugin_scanner-1.0.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: codex-plugin-scanner
+Version: 1.0.0
+Summary: Security and best-practices scanner for Codex CLI plugins. Scores plugins 0-100.
+Project-URL: Homepage, https://github.com/hashgraph-online/codex-plugin-scanner
+Project-URL: Repository, https://github.com/hashgraph-online/codex-plugin-scanner
+Project-URL: Issues, https://github.com/hashgraph-online/codex-plugin-scanner/issues
+Author-email: Hashgraph Online <dev@hol.org>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cli,codex,mcp,plugin,scanner,security
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+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.10
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🔗 Codex Plugin Scanner
+
+[![PyPI version](https://img.shields.io/pypi/v/codex-plugin-scanner.svg)](https://pypi.org/project/codex-plugin-scanner/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codex-plugin-scanner.svg)](https://pypi.org/project/codex-plugin-scanner/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![CI](https://github.com/hashgraph-online/codex-plugin-scanner/actions/workflows/ci.yml/badge.svg)](https://github.com/hashgraph-online/codex-plugin-scanner/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hashgraph-online/codex-plugin-scanner/badge)](https://scorecard.dev/viewer/?uri=github.com/hashgraph-online/codex-plugin-scanner)
+
+A security and best-practices scanner for [Codex CLI plugins](https://developers.openai.com/codex/plugins). Scans plugin directories and outputs a score from 0-100.
+
+## Installation
+
+```bash
+pip install codex-plugin-scanner
+```
+
+Or run directly without installing:
+
+```bash
+pipx run codex-plugin-scanner ./my-plugin
+```
+
+## Usage
+
+```bash
+# Scan a plugin directory
+codex-plugin-scanner ./my-plugin
+
+# Output as JSON
+codex-plugin-scanner ./my-plugin --json
+
+# Write report to file
+codex-plugin-scanner ./my-plugin --output report.json
+```
+
+### Example Output
+
+```
+🔗 Codex Plugin Scanner v1.0.0
+Scanning: ./my-plugin
+
+── Manifest Validation (25/25) ──
+  ✅ plugin.json exists                          +5
+  ✅ Valid JSON                                   +5
+  ✅ Required fields present                      +8
+  ✅ Version follows semver                       +4
+  ✅ Name is kebab-case                           +3
+
+── Security (30/30) ──
+  ✅ SECURITY.md found                           +5
+  ✅ LICENSE found (Apache-2.0)                  +5
+  ✅ No hardcoded secrets detected               +10
+  ✅ No dangerous MCP commands                   +10
+
+── Best Practices (25/25) ──
+  ✅ README.md found                             +5
+  ✅ Skills directory exists if declared          +5
+  ✅ SKILL.md frontmatter                        +5
+  ✅ No .env files committed                     +5
+  ✅ .codexignore found                          +5
+
+── Marketplace (10/10) ──
+  ✅ marketplace.json valid                      +5
+  ✅ Policy fields present                       +5
+
+── Code Quality (10/10) ──
+  ✅ No eval or Function constructor             +5
+  ✅ No shell injection patterns                 +5
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Final Score: 100/100 (A - Excellent)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Scoring Breakdown
+
+| Category | Max Points | Checks |
+|----------|-----------|--------|
+| Manifest Validation | 25 | plugin.json exists, valid JSON, required fields, semver version, kebab-case name |
+| Security | 30 | SECURITY.md, LICENSE, no hardcoded secrets, no dangerous MCP commands |
+| Best Practices | 25 | README.md, skills directory, SKILL.md frontmatter, no .env files, .codexignore |
+| Marketplace | 10 | marketplace.json valid, policy fields present |
+| Code Quality | 10 | no eval/Function, no shell injection |
+
+### Grade Scale
+
+| Score | Grade | Meaning |
+|-------|-------|---------|
+| 90-100 | A | Excellent |
+| 80-89 | B | Good |
+| 70-79 | C | Acceptable |
+| 60-69 | D | Needs Improvement |
+| 0-59 | F | Failing |
+
+## Security Checks
+
+The scanner detects:
+
+- **Hardcoded secrets**: AWS keys, GitHub tokens, OpenAI keys, Slack tokens, GitLab tokens, generic password/secret/token patterns
+- **Dangerous MCP commands**: `rm -rf`, `sudo`, `curl|sh`, `wget|sh`, `eval`, `exec`, `powershell -c`
+- **Shell injection**: template literals with unsanitized interpolation in exec/spawn calls
+- **Unsafe code**: `eval()` and `new Function()` usage
+
+## Use as a GitHub Action
+
+Add to your plugin's CI:
+
+```yaml
+- name: Install scanner
+  run: pip install codex-plugin-scanner
+- name: Scan plugin
+  run: codex-plugin-scanner ./my-plugin
+```
+
+## Use as a pre-commit hook
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: codex-plugin-scanner
+        name: Codex Plugin Scanner
+        entry: codex-plugin-scanner
+        language: system
+        types: [directory]
+        pass_filenames: false
+        args: ["./"]
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src/
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[Apache-2.0](LICENSE) - Hashgraph Online

codex_plugin_scanner-1.0.0/README.md

@@ -0,0 +1,144 @@
+# 🔗 Codex Plugin Scanner
+
+[![PyPI version](https://img.shields.io/pypi/v/codex-plugin-scanner.svg)](https://pypi.org/project/codex-plugin-scanner/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codex-plugin-scanner.svg)](https://pypi.org/project/codex-plugin-scanner/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![CI](https://github.com/hashgraph-online/codex-plugin-scanner/actions/workflows/ci.yml/badge.svg)](https://github.com/hashgraph-online/codex-plugin-scanner/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hashgraph-online/codex-plugin-scanner/badge)](https://scorecard.dev/viewer/?uri=github.com/hashgraph-online/codex-plugin-scanner)
+
+A security and best-practices scanner for [Codex CLI plugins](https://developers.openai.com/codex/plugins). Scans plugin directories and outputs a score from 0-100.
+
+## Installation
+
+```bash
+pip install codex-plugin-scanner
+```
+
+Or run directly without installing:
+
+```bash
+pipx run codex-plugin-scanner ./my-plugin
+```
+
+## Usage
+
+```bash
+# Scan a plugin directory
+codex-plugin-scanner ./my-plugin
+
+# Output as JSON
+codex-plugin-scanner ./my-plugin --json
+
+# Write report to file
+codex-plugin-scanner ./my-plugin --output report.json
+```
+
+### Example Output
+
+```
+🔗 Codex Plugin Scanner v1.0.0
+Scanning: ./my-plugin
+
+── Manifest Validation (25/25) ──
+  ✅ plugin.json exists                          +5
+  ✅ Valid JSON                                   +5
+  ✅ Required fields present                      +8
+  ✅ Version follows semver                       +4
+  ✅ Name is kebab-case                           +3
+
+── Security (30/30) ──
+  ✅ SECURITY.md found                           +5
+  ✅ LICENSE found (Apache-2.0)                  +5
+  ✅ No hardcoded secrets detected               +10
+  ✅ No dangerous MCP commands                   +10
+
+── Best Practices (25/25) ──
+  ✅ README.md found                             +5
+  ✅ Skills directory exists if declared          +5
+  ✅ SKILL.md frontmatter                        +5
+  ✅ No .env files committed                     +5
+  ✅ .codexignore found                          +5
+
+── Marketplace (10/10) ──
+  ✅ marketplace.json valid                      +5
+  ✅ Policy fields present                       +5
+
+── Code Quality (10/10) ──
+  ✅ No eval or Function constructor             +5
+  ✅ No shell injection patterns                 +5
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Final Score: 100/100 (A - Excellent)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Scoring Breakdown
+
+| Category | Max Points | Checks |
+|----------|-----------|--------|
+| Manifest Validation | 25 | plugin.json exists, valid JSON, required fields, semver version, kebab-case name |
+| Security | 30 | SECURITY.md, LICENSE, no hardcoded secrets, no dangerous MCP commands |
+| Best Practices | 25 | README.md, skills directory, SKILL.md frontmatter, no .env files, .codexignore |
+| Marketplace | 10 | marketplace.json valid, policy fields present |
+| Code Quality | 10 | no eval/Function, no shell injection |
+
+### Grade Scale
+
+| Score | Grade | Meaning |
+|-------|-------|---------|
+| 90-100 | A | Excellent |
+| 80-89 | B | Good |
+| 70-79 | C | Acceptable |
+| 60-69 | D | Needs Improvement |
+| 0-59 | F | Failing |
+
+## Security Checks
+
+The scanner detects:
+
+- **Hardcoded secrets**: AWS keys, GitHub tokens, OpenAI keys, Slack tokens, GitLab tokens, generic password/secret/token patterns
+- **Dangerous MCP commands**: `rm -rf`, `sudo`, `curl|sh`, `wget|sh`, `eval`, `exec`, `powershell -c`
+- **Shell injection**: template literals with unsanitized interpolation in exec/spawn calls
+- **Unsafe code**: `eval()` and `new Function()` usage
+
+## Use as a GitHub Action
+
+Add to your plugin's CI:
+
+```yaml
+- name: Install scanner
+  run: pip install codex-plugin-scanner
+- name: Scan plugin
+  run: codex-plugin-scanner ./my-plugin
+```
+
+## Use as a pre-commit hook
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: codex-plugin-scanner
+        name: Codex Plugin Scanner
+        entry: codex-plugin-scanner
+        language: system
+        types: [directory]
+        pass_filenames: false
+        args: ["./"]
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src/
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[Apache-2.0](LICENSE) - Hashgraph Online

codex_plugin_scanner-1.0.0/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.x     | Yes       |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in this project, please report it responsibly:
+
+1. Do not open a public issue.
+2. Email us at security@hol.org with details.
+3. Include steps to reproduce, expected vs actual behavior, and potential impact.
+4. We will acknowledge within 48 hours and aim to resolve within 7 days.
+
+## Security Best Practices
+
+This tool helps you follow security best practices for Codex plugins. For the latest guidance, see the [Codex Security documentation](https://developers.openai.com/codex/security).
+
+### For Plugin Authors
+
+- Never commit API keys, tokens, or secrets to your repository.
+- Use environment variables for sensitive configuration.
+- Avoid dangerous shell commands in `.mcp.json` configurations.
+- Include a `SECURITY.md` in your plugin repository.
+- Use permissive licenses (Apache-2.0 or MIT) for clarity.
+
+### For Scanner Users
+
+- This scanner checks for common patterns but does not guarantee security.
+- Always review plugin code manually before installation.
+- Keep this tool updated for the latest check definitions.