ShiftScope

Migration intelligence for cloud-native infrastructure.

ShiftScope is a pluggable framework for building migration intelligence analyzers for Kubernetes infrastructure API transitions. Unlike API version detectors (Pluto, kubent) that only flag deprecated apiVersion strings, or format converters (ingress2gateway) that only transform YAML, ShiftScope provides semantic risk analysis, implementation matching, and structured migration findings through a pluggable analyzer SDK.

Why ShiftScope?

Quick Start

# Install (requires Python 3.12+)
pip install shiftscope[cli]

# List available analyzers
shiftscope list

# Clone the repo for example files
git clone https://github.com/thc1006/shiftscope.git
cd shiftscope

# Analyze an Ingress manifest for Gateway API migration
shiftscope analyze gateway-api examples/ingress-nginx/basic.yaml --output markdown

# Analyze a NetworkIntent for DRA migration
shiftscope analyze dra-network examples/dra-network-intent.json --output json

# Analyze a Helm chart for v4 readiness
shiftscope analyze helm4-readiness examples/helm-sample-app/ --output markdown

# Analyze an agent config for production readiness
shiftscope analyze agent-readiness examples/agent-readiness.json --output json

Built-in Analyzers

Gateway API (gateway-api)

Ingress NGINX → Gateway API migration intelligence.

• 5 annotation portability rules (CORS, backend-protocol, auth-tls-secret, server-snippet, ssl-redirect)
• 3 TLS risk rules (wildcard TLS, frontend mTLS/coalescing, backend protocol)
• 1 unknown annotation catcher
• 6 implementation profiles (Envoy Gateway, NGINX Gateway Fabric, Cilium, Kong, Contour, Traefik)

DRA Networking (dra-network)

Device Plugin → Dynamic Resource Allocation migration intelligence.

• Alpha feature gate detection (extended_resource_mapping, consumable_capacity, partitionable_devices)
• RDMA/bandwidth requirements analysis
• Legacy bridge (SR-IOV/Multus) migration path detection
• Topology alignment (NUMA/PCI) requirements
• Workload kind validation

Helm 4 Readiness (helm4-readiness)

Helm 3 → Helm 4 / Charts v3 readiness analysis.

• Chart API v2 detection with v3 migration guidance
• Go template complexity analysis
• Resource sequencing needs (HIP-0025)
• .helmignore parity review
• Values parent/subchart transform detection

Telco Intent (telco-intent)

Telco YANG → GitOps intent provenance analysis.

• GitOps target validation (Flux/Nephio K8s version conflict)
• Provenance review (hydration/IPAM fields need human review)
• SDC southbound contract-only warning

Agent Readiness (agent-readiness)

AI agent pilot → production readiness assessment.

• Tool allowlist compliance (blocks unapproved tools)
• Token budget enforcement + cost governance (no-budget, no-loop-guard, unbounded-retry)
• Observability gating (OTEL + trace coverage >= 80%)
• Weighted promotion gate (security 0.4 + observability 0.35 + economics 0.25)
• Kill switch, audit trail, and graduated response (75%/90%/100%) checks

MCP Security (mcp-security)

MCP server configuration security scanning (OWASP ASI mapped).

• Static credentials detection (plaintext API keys/tokens in env vars)
• Missing authentication (CVE-2026-32211 pattern)
• Command injection risk (shell-executing MCP servers)
• Over-permission (wildcard permissions, unsafe flags)
• Supply chain (unpinned npx/uvx/pipx packages)

Architecture

┌──────────────────────────────────────────────────┐
│                 ShiftScope SDK                    │
│                                                  │
│  Core Models ─── Renderers ─── Eval Harness      │
│  (Pydantic)      (JSON/MD)    (golden-file)      │
│                                                  │
│  Rule ABC ────── Analyzer ABC ── Registry        │
│  (applies_to     (run_rules)    (entry_points    │
│   + evaluate)                    discovery)       │
│                                                  │
│  CLI ─────────── MCP Bridge ─── AI Augment       │
│  (Typer,          (FastMCP,      (PydanticAI,    │
│   auto-gen)        auto-gen)      optional)      │
│                                                  │
│  MCP Discovery ── A2A Agent Card                 │
│  (.well-known)    (capabilities)                 │
└──────────────────────────────────────────────────┘
     │          │          │          │          │        │
 Gateway    DRA        Helm 4    Telco      Agent    MCP
 API        Network    Readiness Intent     Readiness Security

Writing a Custom Analyzer

from shiftscope import Analyzer, Rule, Finding, Severity, Report

class MyRule(Rule):
    rule_id = "my-check"
    severity = Severity.WARNING

    def applies_to(self, context):
        return "config" in context

    def evaluate(self, context):
        if context["config"].get("deprecated_field"):
            return Finding(
                rule_id=self.rule_id,
                severity=self.severity,
                title="Deprecated field detected",
                detail="This field is removed in the next version.",
                evidence=f"deprecated_field={context['config']['deprecated_field']}",
                recommendation="Migrate to the new field.",
            )
        return None

class MyAnalyzer(Analyzer):
    name = "my-analyzer"
    version = "0.1.0"
    description = "Custom migration analyzer"

    def __init__(self):
        self._rules = [MyRule()]

    def analyze(self, input_path, **kwargs):
        import json
        from pathlib import Path
        config = json.loads(Path(input_path).read_text(encoding="utf-8"))
        context = {"config": config}
        return Report(
            analyzer_name=self.name,
            analyzer_version=self.version,
            source=input_path,
            findings=self.run_rules(context),
        )

    def list_rules(self):
        return list(self._rules)

Register via entry points in your pyproject.toml:

[project.entry-points."shiftscope.analyzers"]
my-analyzer = "my_package:MyAnalyzer"

MCP Integration

ShiftScope exposes all analyzers as MCP tools for AI agent consumption. Requires the MCP extra: pip install shiftscope[mcp] (or shiftscope[full]).

from shiftscope.mcp.bridge import create_mcp_server
from shiftscope.core.analyzer import AnalyzerRegistry

registry = AnalyzerRegistry()
registry.discover()
mcp = create_mcp_server(registry)
mcp.run()  # Exposes analyze_gateway_api, analyze_dra_network, etc.

GitHub Action

Run ShiftScope in your CI/CD pipeline with PR comments and GitHub Code Scanning:

# .github/workflows/shiftscope.yml
- uses: thc1006/shiftscope/github-action@v1
  with:
    analyzer: gateway-api
    input-path: ./manifests/ingress.yaml
    output-format: sarif
    fail-on-critical: 'true'
    post-pr-comment: 'true'

See github-action/example-workflow.yml for a complete example with SARIF upload to Code Scanning.

Argo Workflows

Run ShiftScope as an Argo Workflows pipeline step with conditional gates:

- templateRef:
    name: shiftscope-analyze
    template: analyze
  arguments:
    parameters:
      - name: analyzer
        value: gateway-api
      - name: input-path
        value: ingress.yaml
      - name: fail-on-critical
        value: "true"

Prerequisite: Apply the WorkflowTemplate first: kubectl apply -f examples/argo-workflow-template.yaml

Note: The shiftscope-analyze template requires a manifests input artifact. Wire it from a previous step (e.g., git-clone) as shown in the full example.

See examples/argo-workflow-template.yaml for the full WorkflowTemplate and examples/argo-workflow-example.yaml for a complete example.

Development

git clone https://github.com/thc1006/shiftscope.git
cd shiftscope
make bootstrap    # requires uv
make test         # run tests
make lint         # ruff check
make verify       # lint + test + compileall

Roadmap

See ADR-001 for the full architectural decision record, cross-validation results, and phase-by-phase roadmap.

License

Apache License 2.0