ai-agentic-mcpscan 0.1.0__tar.gz

ai_agentic_mcpscan-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Report incorrect behavior (including false positives / false negatives)
+title: "[bug] "
+labels: bug
+---
+
+**⚠️ Do not paste real secrets or full config contents.** Redact anything
+sensitive — `mcpscan` is designed so you never need to share a secret to report
+a bug.
+
+## What happened
+A clear description of the bug.
+
+## Expected
+What you expected instead.
+
+## Finding accuracy (if relevant)
+- [ ] False positive (flagged something that is actually fine)
+- [ ] False negative (missed something it should have flagged)
+
+A **minimal, sanitized** config that reproduces it:
+
+```json
+{ }
+```
+
+## Environment
+- mcpscan version (`mcpscan --version`):
+- OS:
+- Python version:
+- Command used (with flags):

ai_agentic_mcpscan-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,7 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 🔒 Report a security vulnerability
+    url: https://github.com/IRsoctierDT/ai-agentic-mcpscan/security/advisories/new
+    about: >-
+      Please report vulnerabilities privately via a GitHub Security Advisory,
+      not a public issue. See SECURITY.md.

ai_agentic_mcpscan-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Suggest a new check, host adapter, or capability
+title: "[feat] "
+labels: enhancement
+---
+
+## Problem
+What posture gap or workflow pain does this address?
+
+## Proposal
+What you'd like the tool to do.
+
+## Type
+- [ ] New check (which posture dimension: exposure / credential / tool-scope / pinning?)
+- [ ] New host adapter (which host?)
+- [ ] Output / reporting
+- [ ] Other
+
+## Trust considerations
+Does this involve network access, writing files, or handling secrets? If so, how
+should it stay consistent with the offline-default, advise-only, redacted design?

ai_agentic_mcpscan-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What & why
+Briefly: what this changes and the motivation.
+
+## Checklist
+- [ ] `ruff check .`, `ruff format --check .`, `mypy src`, `bandit -r src`,
+      `pytest` all pass locally
+- [ ] New logic has tests, including failure/edge cases
+- [ ] New check ships with a clean/negative fixture (zero findings on good input)
+- [ ] No raw secret can reach output, logs, or disk
+- [ ] No egress added outside `enrichment/` / outside `--online`
+- [ ] No writes to user config files (advise-only preserved)
+- [ ] Docs updated if behavior/flags changed
+
+## Notes for the reviewer
+Anything you want a second set of eyes on (trust boundaries, false-positive risk).

ai_agentic_mcpscan-0.1.0/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  # Python dependencies (declared in pyproject.toml).
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels: ["dependencies"]
+    commit-message:
+      prefix: "build"
+      include: "scope"
+
+  # GitHub Actions used by our workflows.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels: ["ci", "dependencies"]
+    commit-message:
+      prefix: "ci"

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

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (editable + dev)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Lint (ruff)
+        run: ruff check .
+      - name: Format check (ruff)
+        run: ruff format --check .
+      - name: Type check (mypy)
+        run: mypy src
+      - name: Tests
+        # Coverage gate (branch=true + fail_under) lives in pyproject.toml
+        # [tool.coverage.*], so this command enforces it without duplicating
+        # the threshold here. Under-threshold coverage fails the job.
+        run: pytest --cov=mcpscan --cov-report=term-missing
+
+  security:
+    name: security (SAST + SCA)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: SAST (bandit)
+        run: bandit -r src
+      - name: SCA (pip-audit)
+        run: pip-audit

ai_agentic_mcpscan-0.1.0/.github/workflows/dependency-review.yml

@@ -0,0 +1,27 @@
+name: Dependency Review
+
+# Blocks a PR that introduces a dependency with a known vulnerability or a
+# disallowed license. Runs on the PR's dependency diff.
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write # to post the summary comment on failure
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    # Dependency review needs the dependency graph, which is free on public
+    # repos and requires GitHub Advanced Security on private ones. Skip (neutral)
+    # while private; self-activates automatically when the repo goes public.
+    if: ${{ github.event.repository.visibility == 'public' }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Dependency review
+        uses: actions/dependency-review-action@v5
+        with:
+          fail-on-severity: high
+          comment-summary-in-pr: on-failure

ai_agentic_mcpscan-0.1.0/.github/workflows/pr-title.yml

@@ -0,0 +1,38 @@
+name: PR Title
+
+# Enforces Conventional Commit PR titles (the squash-merge commit subject).
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR title
+        uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            security
+            chore
+            revert
+          requireScope: false
+          subjectPattern: ^(?![A-Z]).+$
+          subjectPatternError: |
+            The subject "{subject}" should start lowercase (imperative mood),
+            e.g. "feat(checks): add TLS-misconfig detection".

ai_agentic_mcpscan-0.1.0/.github/workflows/release-please.yml

@@ -0,0 +1,75 @@
+name: release-please
+
+# Automated releases from Conventional Commits (Phase 3).
+#
+# On each push to main, release-please maintains a "release PR" that bumps the
+# version in pyproject.toml and updates CHANGELOG.md. Merging that PR tags the
+# release and creates a GitHub Release; the publish job then builds and pushes to
+# PyPI via Trusted Publishing (OIDC — no stored token), gated on the `pypi`
+# environment (add a required reviewer there for a manual production gate).
+#
+# NOTE: v0.1.0 is released via the manual path (.github/workflows/release.yml);
+# the manifest is seeded at 0.1.0 so release-please starts proposing 0.1.1+.
+#
+# Operator step: on PyPI, add a Trusted Publisher for THIS workflow filename
+# (release-please.yml) + environment `pypi`, alongside the existing release.yml
+# one. See docs/DEVSECOPS.md.
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.rp.outputs.release_created }}
+      tag_name: ${{ steps.rp.outputs.tag_name }}
+    steps:
+      - id: rp
+        uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC Trusted Publishing
+      contents: write # attach SBOM + checksums to the release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Generate checksums
+        run: sha256sum dist/* > SHA256SUMS
+
+      - name: Generate CycloneDX SBOM
+        run: |
+          python -m pip install cyclonedx-bom
+          python -m pip install .
+          cyclonedx-py environment -o sbom.cdx.json
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Attach SBOM + checksums to the release
+        uses: softprops/action-gh-release@v3
+        with:
+          tag_name: ${{ needs.release-please.outputs.tag_name }}
+          files: |
+            SHA256SUMS
+            sbom.cdx.json

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

@@ -0,0 +1,52 @@
+name: Release
+
+# Publishes to PyPI via Trusted Publishing (OIDC) — NO API token stored in the
+# repo. Runs only when a GitHub Release is published, so publishing is an
+# explicit human action (create the release in the UI / `gh release create`).
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Verify tag matches package version
+        run: |
+          python -m pip install --upgrade pip
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG="${GITHUB_REF_NAME#v}"
+          echo "package=$PKG_VERSION tag=$TAG"
+          test "$PKG_VERSION" = "$TAG" || { echo "::error::tag ($TAG) != version ($PKG_VERSION)"; exit 1; }
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi  # add a manual-approval rule on this environment for extra safety
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

ai_agentic_mcpscan-0.1.0/.github/workflows/sbom.yml

@@ -0,0 +1,43 @@
+name: SBOM & Checksums
+
+# On a published Release, attach a CycloneDX SBOM and SHA-256 checksums as
+# release assets. Independent of release.yml (the publish path) so it can never
+# affect publishing.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write # attach assets to the release that triggered this run
+
+jobs:
+  sbom:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Generate checksums
+        run: (cd dist && sha256sum * > SHA256SUMS && cat SHA256SUMS)
+
+      - name: Generate CycloneDX SBOM
+        run: |
+          python -m pip install cyclonedx-bom
+          python -m pip install .
+          cyclonedx-py environment -o sbom.cdx.json
+          echo "wrote sbom.cdx.json"
+
+      - name: Attach SBOM + checksums to the release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: |
+            dist/SHA256SUMS
+            sbom.cdx.json

ai_agentic_mcpscan-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# macOS
+.DS_Store
+
+# Secrets / local config — never commit (this is a security tool; lead by example)
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+
+# Tool output (stateless by design — never commit generated reports)
+*.mcpscan.html
+*.mcpscan.json
+
+# Claude Code local settings
+.claude/settings.local.json

ai_agentic_mcpscan-0.1.0/.gitmessage

@@ -0,0 +1,27 @@
+# <type>(<optional scope>): <subject>        <- 50 chars, imperative, lowercase
+#
+# <body: what changed and WHY. Wrap at 72.>
+#
+# <footers: "Refs: #123", "BREAKING CHANGE: <desc>">
+#
+# ---------------------------------------------------------------------------
+# Conventional Commits (https://www.conventionalcommits.org)
+# Types:
+#   feat     – a new feature                 (→ minor release)
+#   fix      – a bug fix                      (→ patch release)
+#   perf     – a performance improvement      (→ patch release)
+#   security – a security fix/hardening       (→ patch release)
+#   docs     – documentation only
+#   test     – tests only
+#   refactor – neither fixes a bug nor adds a feature
+#   style    – formatting, no code change
+#   build    – build system / dependencies
+#   ci       – CI configuration
+#   chore    – other maintenance
+#   revert   – reverts a previous commit
+#
+# Breaking change: add "!" after the type/scope (feat!:) OR a
+# "BREAKING CHANGE:" footer  (→ major release).
+#
+# Enable this template once:  git config commit.template .gitmessage
+# ---------------------------------------------------------------------------

ai_agentic_mcpscan-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

ai_agentic_mcpscan-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0]
+
+First public release — a local-first, offline-by-default security posture
+scanner for MCP / local-agent setups (CLI: `mcpscan`).
+
+### Added
+
+- **CLI** — `mcpscan scan` with `--root`, `--json`, `--html`, `--online`,
+  `--show-secrets`, `--absolute-paths`, and `--fail-on {critical,high,medium,low}`;
+  process exit code is driven by the highest finding severity versus the
+  threshold.
+- **Discovery** — listening-socket enumeration via psutil (degrades gracefully
+  when the OS denies introspection), a loopback-only MCP confirmation probe
+  (`/mcp`, `/sse`), and declared-server discovery from Claude Code / Claude
+  Desktop configs through a `HostAdapter` seam.
+- **Checks (four dimensions)** — exposure (non-loopback / `0.0.0.0` binds),
+  credentials (plaintext secrets by provider pattern + entropy, and secret-at-rest
+  file permission / git-tracking), tool scope (auto-approved and wildcard
+  permission grants), and version pinning (unpinned `npx`/`uvx`/etc.).
+- **Scoring** — deterministic A–F grading per server, per dimension, and overall.
+- **Reports** — ANSI terminal output, stable machine-readable JSON
+  (`schema_version` "1.0"), and a self-contained, offline HTML report.
+- **Online enrichment** — opt-in `--online` OSV advisory lookups for pinned
+  packages; the egress module is isolated and imported only on this path.
+- **Self-scan** (`mcpscan` passes its own checks) and cross-platform CI
+  (macOS/Linux/Windows × Python 3.11–3.13).
+
+### Security & trust properties
+
+- Offline by default; no network egress unless `--online` is passed.
+- Loopback-only probing — non-loopback targets are refused (fail closed).
+- Secrets are reduced to fingerprints at detection; raw values never reach the
+  domain model, reports, or logs. `--show-secrets` reveals only a masked form and
+  prints a warning.
+- No file writes except the reports you explicitly request, created `0600` where
+  supported.
+- Home directories are relativized to `~/…` by default (`--absolute-paths` opts
+  out).
+
+### Packaging
+
+- Apache-2.0 licensed, with a `NOTICE` file and per-file SPDX headers.
+- Publishes to PyPI via Trusted Publishing (OIDC); the version is single-sourced
+  from `pyproject.toml`.
+
+[0.1.0]: https://github.com/IRsoctierDT/ai-agentic-mcpscan/releases/tag/v0.1.0

ai_agentic_mcpscan-0.1.0/CODEOWNERS

@@ -0,0 +1,15 @@
+# Code owners — auto-requested as reviewers on matching paths.
+# Docs: https://docs.github.com/articles/about-code-owners
+
+# Default owner for everything.
+*                           @IRsoctierDT
+
+# Security-critical surfaces get explicit ownership.
+/src/mcpscan/redaction.py   @IRsoctierDT
+/src/mcpscan/enrichment/    @IRsoctierDT
+/src/mcpscan/discovery/     @IRsoctierDT
+
+# CI/CD, supply chain, and governance.
+/.github/                   @IRsoctierDT
+/SECURITY.md                @IRsoctierDT
+/pyproject.toml             @IRsoctierDT

ai_agentic_mcpscan-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,80 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**irozenblad@icloud.com**. All complaints will be reviewed and investigated
+promptly and fairly. All community leaders are obligated to respect the privacy
+and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+1. **Correction** — Community Impact: use of inappropriate language or other
+   unprofessional behavior. Consequence: a private, written warning.
+2. **Warning** — Community Impact: a violation through a single incident or
+   series of actions. Consequence: a warning with consequences for continued
+   behavior.
+3. **Temporary Ban** — Community Impact: a serious violation of community
+   standards. Consequence: a temporary ban from any interaction with the
+   community.
+4. **Permanent Ban** — Community Impact: demonstrating a pattern of violation of
+   community standards. Consequence: a permanent ban.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

ai_agentic_mcpscan-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to AI Agentic MCPscan
+
+Thanks for your interest! This project aims to be exemplary, reviewable security
+tooling, so contributions are held to a clear bar.
+
+## Quick start
+
+```bash
+git clone https://github.com/IRsoctierDT/ai-agentic-mcpscan.git
+cd ai-agentic-mcpscan
+python -m venv .venv && . .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+## Run the full gate before opening a PR
+
+```bash
+ruff check .            # lint
+ruff format --check .   # formatting
+mypy src                # types (strict)
+bandit -r src           # SAST
+pytest                  # tests
+```
+
+CI runs the same gate on macOS, Linux, and Windows across Python 3.11–3.13. All
+of it must be green.
+
+## Architecture & where things go
+
+- The design is documented in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+  Read it first — the dependency direction (pure core, I/O at the edges) is
+  intentional.
+- **New host support** → add a `HostAdapter` in `src/mcpscan/adapters/`. The
+  engine and checks must not need to change.
+- **New check** → add a small, single-responsibility function in
+  `src/mcpscan/checks/`, plus a **clean/negative fixture** (an input that must
+  produce zero findings) alongside the positive test. False positives are
+  treated as bugs.
+- **Anything touching the network** belongs only in `src/mcpscan/enrichment/`
+  and must stay behind `--online`.
+
+## Non-negotiables (will block a PR)
+
+- No raw secret value may reach output, logs, or disk. Route secrets through
+  `redaction`.
+- No egress on a default (non-`--online`) run.
+- No writing to a user's config files (advise-only).
+- New logic ships with tests, including failure/edge cases.
+
+## Commit style
+
+Conventional commits (`feat:`, `fix:`, `docs:`, `chore:`, `test:`) scoped where
+useful (e.g. `feat(checks): …`). PR titles are checked against this format by
+CI. To get a helpful template in your editor:
+
+```bash
+git config commit.template .gitmessage
+```
+
+## Workflow, branching & releases
+
+The full Git workflow, CI/CD pipeline, branch-protection settings, semantic
+versioning, rollback, and release process are documented in
+[`docs/DEVSECOPS.md`](docs/DEVSECOPS.md). In short: branch `feature/*` off
+`main`, keep it short-lived, open a PR, get CI green + one review, and squash-merge.
+
+Participation is governed by our [Code of Conduct](CODE_OF_CONDUCT.md).