shiftscope 0.3.1

Migration intelligence framework for cloud-native infrastructure API transitions

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?

Tool	Detection	Conversion	Risk Analysis	MCP	Pluggable SDK
Pluto / kubent	apiVersion only	-	-	-	-
ingress2gateway	-	YAML transform	-	-	-
Konveyor AI	app code	app code	app-layer	partial	-
ShiftScope	semantic	-	annotations, TLS, feature gates	native	yes

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.

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.

Phase	Status	Scope
1: Core SDK + Reference Analyzer	Done	Models, Rule/Analyzer ABC, renderers, CLI, MCP bridge, Gateway API analyzer
2: Multi-Analyzer + CI	Done	DRA + Helm 4 analyzers, GitHub Actions CI, CodeQL
3: AI + Security	Done	Telco + agent analyzers, PydanticAI, A2A, behavioral detection, MCP security, agent governance v2
4: CNCF Sandbox	Planned	Landscape listing, TAG presentation, Sandbox proposal
5: Ecosystem	Planned	GitHub Action, Argo Workflows, KubeCon NA 2026

License

Apache License 2.0