shieldops-sdk 0.1.0__tar.gz

shieldops_sdk-0.1.0/.gitattributes

@@ -0,0 +1,36 @@
+# Normalize line endings on commit; check out with platform-native endings.
+* text=auto eol=lf
+
+# Source / docs / config — always LF, always text.
+*.py    text eol=lf
+*.pyi   text eol=lf
+*.md    text eol=lf
+*.rst   text eol=lf
+*.txt   text eol=lf
+*.toml  text eol=lf
+*.yaml  text eol=lf
+*.yml   text eol=lf
+*.json  text eol=lf
+*.cfg   text eol=lf
+*.ini   text eol=lf
+
+# Shell scripts must stay LF even on Windows clones.
+*.sh    text eol=lf
+Makefile text eol=lf
+
+# Common binaries — never normalize.
+*.png   binary
+*.jpg   binary
+*.jpeg  binary
+*.gif   binary
+*.ico   binary
+*.pdf   binary
+*.zip   binary
+*.gz    binary
+*.tar   binary
+*.whl   binary
+
+# Linguist hints for GitHub's language stats.
+docs/**           linguist-documentation
+examples/**       linguist-documentation
+tests/**          linguist-detectable=false

shieldops_sdk-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,22 @@
+# CODEOWNERS for shieldops-sdk
+#
+# Every path in this repository is owned by at least one reviewer listed
+# below. Pull requests automatically request review from the matching
+# owner. Order matters: the last matching pattern wins for a given path.
+#
+# TODO: replace @ghantakiran with team handles (e.g. @shieldops/maintainers,
+# @shieldops/security) after the GitHub organization is provisioned and
+# the maintainers/security teams exist. See HITL-SETUP.md.
+
+* @ghantakiran
+
+# Security-sensitive paths require a security reviewer in addition to
+# the default owner. After org setup, add @shieldops/security here.
+/SECURITY.md            @ghantakiran
+/.github/               @ghantakiran
+/src/shieldops_sdk/     @ghantakiran
+
+# Release + license docs require a maintainer review.
+/LICENSE                @ghantakiran
+/CHANGELOG.md           @ghantakiran
+/pyproject.toml         @ghantakiran

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

@@ -0,0 +1,39 @@
+---
+name: Bug report
+about: Report a defect in shieldops-sdk
+title: "[bug] "
+labels: ["bug", "triage"]
+assignees: []
+---
+
+## Reproduction
+
+Steps to reproduce the behavior. A minimal code sample is ideal.
+
+```python
+# paste minimal repro here
+```
+
+## Expected
+
+What you expected to happen.
+
+## Actual
+
+What actually happened. Include the full traceback if an exception was
+raised. Redact any API keys, tokens, or customer data before posting.
+
+## Environment
+
+| Field | Value |
+|-------|-------|
+| Python version | e.g. 3.12.2 |
+| `shieldops-sdk` version | e.g. 1.0.0 |
+| Integration framework | e.g. LangChain 0.2.5 / CrewAI 0.30 / LlamaIndex 0.10 / none |
+| Operating system | e.g. macOS 14.4 / Ubuntu 22.04 / Windows 11 |
+| SDK mode | `audit` or `enforce` |
+
+## Additional context
+
+Logs, screenshots, or anything else that helps. Remember: do not paste
+secrets.

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

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability report
+    url: https://github.com/shieldops/shieldops-sdk/blob/main/SECURITY.md
+    about: Do not report security issues in public GitHub issues. See SECURITY.md for the private disclosure process and our response SLAs.
+  - name: Usage questions and discussions
+    url: https://github.com/shieldops/shieldops-sdk/discussions
+    about: For general questions about using shieldops-sdk, open a discussion instead of an issue.

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

@@ -0,0 +1,37 @@
+---
+name: Feature request
+about: Propose an enhancement to shieldops-sdk
+title: "[feat] "
+labels: ["enhancement", "triage"]
+assignees: []
+---
+
+## Use case
+
+What are you trying to accomplish? Describe the user or system problem,
+not the solution.
+
+## Current workaround
+
+How are you solving this today, if at all? Include code if helpful.
+
+## Proposed API
+
+What would the ideal public API look like? Sketch the shape in code:
+
+```python
+# your proposed usage
+```
+
+Call out any new public classes, methods, config fields, or env vars.
+
+## Alternatives considered
+
+What other approaches did you evaluate? Why did you rule them out?
+
+## Additional context
+
+Links to related issues, upstream framework docs, prior art in other
+SDKs, or benchmarks. If this is a new framework integration, also read
+the "Proposing a new framework integration" section of
+`CONTRIBUTING.md` before filing.

shieldops_sdk-0.1.0/.github/ISSUE_TEMPLATE/security_advisory.md

@@ -0,0 +1,22 @@
+---
+name: Security issue (do not use)
+about: Redirects to SECURITY.md
+title: "[security] DO NOT FILE HERE"
+labels: ["security"]
+assignees: []
+---
+
+## Do not report security issues here
+
+Public issues are visible to everyone, including attackers. Reporting a
+vulnerability here can put users at risk before a patch is available.
+
+Instead, follow the process in [`SECURITY.md`](../../SECURITY.md):
+
+- Email **security@shieldops.io** with details.
+- Encrypt sensitive reports with the PGP key referenced in `SECURITY.md`.
+- Expect an acknowledgement within the SLA published in that document.
+
+If you opened this template by mistake, please close it and redirect
+your report to the email address above. Thank you for helping keep
+`shieldops-sdk` users safe.

shieldops_sdk-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,44 @@
+## Summary
+
+One-paragraph description of what this PR changes and why. Focus on the
+"why" -- the diff already shows the "what".
+
+## Linked issue
+
+Closes #<issue-number>
+
+(Use `Closes` / `Fixes` for bug fixes, `Refs` for partial work.)
+
+## Tests added
+
+- [ ] Unit tests for new code paths
+- [ ] Integration tests updated if public behavior changed
+- [ ] Coverage on changed lines is >= 80%
+- [ ] `pytest tests/ -v` passes locally
+
+Describe what the new tests cover and how they exercise the change.
+
+## DCO signed
+
+- [ ] Every commit on this branch is signed off with `git commit -s`
+      (adds a `Signed-off-by:` trailer). The DCO bot blocks merge
+      otherwise. See `CONTRIBUTING.md` for details.
+
+## Breaking change?
+
+- [ ] Yes -- describe the break and the migration path below.
+- [ ] No.
+
+If yes: document the before/after API, whether a deprecation period
+was offered, and link the RFC issue that approved the break.
+
+## Checklist
+
+- [ ] `ruff check src/ tests/` passes with no new warnings
+- [ ] `ruff format --check src/ tests/` passes
+- [ ] `pytest tests/ -v --tb=short` passes
+- [ ] Type hints on all new public functions and methods
+- [ ] Docstrings on all new public classes, functions, and methods
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] Documentation updated in `docs/` if public behavior changed
+- [ ] No secrets, API keys, or customer data in the diff or tests

shieldops_sdk-0.1.0/.github/dependabot.yml

@@ -0,0 +1,62 @@
+# Dependabot config for shieldops-sdk (PRD-028 PR α).
+#
+# Authored in the private monorepo at sdk/.github/dependabot.yml; rides
+# the carve-out mirror to shieldops-io/shieldops-sdk.
+#
+# SLA per PRD-028 §"PR α / Acceptance criteria":
+#   - high-severity advisories  → 7 days
+#   - medium-severity advisories → 30 days
+#
+# Dependabot itself respects the GitHub Advisory Database for severity
+# labeling; the timelines above are enforced by team policy + the
+# auto-merge schedule below (informational `commit-message.prefix`
+# tagging that monitoring can grep).
+
+version: 2
+
+updates:
+  # ── Python (the SDK itself) ──────────────────────────────────────────
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "deps(pip)"
+      include: "scope"
+    groups:
+      runtime:
+        patterns:
+          - "*"
+        exclude-patterns:
+          - "pytest*"
+          - "ruff"
+          - "mypy"
+          - "hatch*"
+          - "build"
+      dev:
+        patterns:
+          - "pytest*"
+          - "ruff"
+          - "mypy"
+          - "hatch*"
+          - "build"
+    # Security-only updates run on a tighter cadence — Dependabot opens
+    # those PRs immediately on advisory publish.
+    labels:
+      - "dependencies"
+      - "python"
+
+  # ── GitHub Actions (release.yml + ci.yml) ────────────────────────────
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "deps(actions)"
+    labels:
+      - "dependencies"
+      - "github-actions"

shieldops_sdk-0.1.0/.github/scripts/assemble_release_evidence.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# sdk/.github/scripts/assemble_release_evidence.sh — PRD-028 PR α companion.
+#
+# Invoked by release.yml after verify-published succeeds. Collects build
+# metadata + SBOM digest + SLSA provenance URL + Sigstore bundle ref +
+# private-source SHA, writes RELEASE_EVIDENCE.md, and attaches it as a
+# GitHub Release asset.
+#
+# Row schema is forward-compatible with PRD-013 Merkle ledger.
+#
+# Required environment:
+#   GITHUB_REF_NAME         — the sdk-v<X.Y.Z> tag
+#   GITHUB_SHA              — the tagged commit SHA on the public repo
+#   SDK_VERSION             — X.Y.Z (resolved by release.yml/prepare)
+#   IS_RC                   — "true" or "false"
+#   SDIST_SHA256            — from release.yml/build
+#   WHEEL_SHA256            — from release.yml/build
+#   SBOM_PATH               — path to sbom.cdx.json (downloaded artifact)
+#   SLSA_PROVENANCE_URL     — URL to the .intoto.jsonl provenance asset
+#   SIGSTORE_BUNDLE         — Sigstore signing bundle ref (set by publish job)
+#   PRIVATE_REPO_READ_TOKEN — fine-grained PAT, read-only, single path on
+#                             ghantakiran/ShieldOps; used to resolve the
+#                             matching private source SHA from
+#                             tools/SDK_TREE_PINS.txt.
+#
+# Output:
+#   RELEASE_EVIDENCE.md in repo root, then `gh release upload`'d.
+
+set -euo pipefail
+
+: "${GITHUB_REF_NAME:?}"
+: "${GITHUB_SHA:?}"
+: "${SDK_VERSION:?}"
+: "${SDIST_SHA256:?}"
+: "${WHEEL_SHA256:?}"
+
+# Optional with sensible defaults so the script is testable locally.
+IS_RC="${IS_RC:-false}"
+SBOM_PATH="${SBOM_PATH:-sbom.cdx.json}"
+SLSA_PROVENANCE_URL="${SLSA_PROVENANCE_URL:-pending}"
+SIGSTORE_BUNDLE="${SIGSTORE_BUNDLE:-pending}"
+
+# Resolve the matching private-source SHA from tools/SDK_TREE_PINS.txt
+# on the private monorepo using the single-path read-only PAT. The pin
+# file is the only file this token can read.
+PRIVATE_SOURCE_SHA="unknown"
+if [[ -n "${PRIVATE_REPO_READ_TOKEN:-}" ]]; then
+    PINS=$(curl -sf \
+        -H "Accept: application/vnd.github.raw" \
+        -H "Authorization: Bearer ${PRIVATE_REPO_READ_TOKEN}" \
+        "https://api.github.com/repos/ghantakiran/ShieldOps/contents/tools/SDK_TREE_PINS.txt" \
+        || echo "")
+    if [[ -n "${PINS}" ]]; then
+        PRIVATE_SOURCE_SHA=$(echo "${PINS}" \
+            | awk -v ver="${SDK_VERSION}" '
+                $0 ~ "^sdk-v"ver"$" { found=1; next }
+                found && /^private_main_sha:/ { print $2; exit }
+            ' || echo "lookup-failed")
+    fi
+fi
+
+SBOM_DIGEST="unknown"
+if [[ -f "${SBOM_PATH}" ]]; then
+    SBOM_DIGEST=$(sha256sum "${SBOM_PATH}" | cut -d' ' -f1)
+fi
+
+cat > RELEASE_EVIDENCE.md <<EOF
+# Release Evidence — ${GITHUB_REF_NAME}
+
+This file is auto-generated by .github/scripts/assemble_release_evidence.sh.
+Schema is forward-compatible with the PRD-013 Merkle ledger.
+
+| Field | Value |
+|---|---|
+| Tag | \`${GITHUB_REF_NAME}\` |
+| SDK version | \`${SDK_VERSION}\` |
+| Release candidate | \`${IS_RC}\` |
+| Public release SHA | \`${GITHUB_SHA}\` |
+| Private source SHA | \`${PRIVATE_SOURCE_SHA}\` |
+| sdist SHA-256 | \`${SDIST_SHA256}\` |
+| wheel SHA-256 | \`${WHEEL_SHA256}\` |
+| SBOM (CycloneDX) digest | \`${SBOM_DIGEST}\` |
+| SLSA provenance | ${SLSA_PROVENANCE_URL} |
+| Sigstore bundle | ${SIGSTORE_BUNDLE} |
+| Generated at | $(date -u +%Y-%m-%dT%H:%M:%SZ) |
+
+## Verifying this release
+
+\`\`\`bash
+# Verify the wheel matches the published artifact
+pip download --no-deps shieldops-sdk==${SDK_VERSION} -d /tmp/verify
+sha256sum /tmp/verify/shieldops_sdk-*.whl  # should match wheel SHA-256 above
+
+# Verify Sigstore signature (after PR β #647 lands)
+python -m sigstore verify identity \\
+    --bundle "\${SIGSTORE_BUNDLE_PATH}" \\
+    --cert-identity-regexp '^https://github.com/shieldops-io/shieldops-sdk/' \\
+    --cert-oidc-issuer https://token.actions.githubusercontent.com \\
+    /tmp/verify/shieldops_sdk-*.whl
+
+# Verify SLSA provenance via slsa-verifier
+slsa-verifier verify-artifact /tmp/verify/shieldops_sdk-*.whl \\
+    --provenance-path provenance.intoto.jsonl \\
+    --source-uri github.com/shieldops-io/shieldops-sdk \\
+    --source-tag ${GITHUB_REF_NAME}
+\`\`\`
+EOF
+
+echo "RELEASE_EVIDENCE.md written:"
+cat RELEASE_EVIDENCE.md

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

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (ruff check)
+        run: ruff check src/ tests/
+
+      - name: Format (ruff format --check)
+        run: ruff format --check src/ tests/
+
+      - name: Test (pytest)
+        run: pytest tests/ -v --tb=short
+
+  dco:
+    name: DCO sign-off check
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Verify DCO
+        uses: tim-actions/dco@v1.1.0