Policy Customization - Getting Started

Customize containerization policies using the priority-ordered policy system.

Quickstart - Guided

The fastest way to create a policy is the create-containerization-policy tool. Run it from your MCP client (VS Code Copilot, Claude Desktop, etc.):

Use the create-containerization-policy tool to help me set up a policy

The tool walks you through each decision:

1. Policy type — Dockerfile (image) or Kubernetes manifest
2. What to enforce — base image allowlist, security rules, resource limits, etc.
3. Severity — block (reject non-compliant content) or warn (advisory only)
4. Scope — project-local (.containerization-assist/policy/) or global (~/.config/containerization-assist/policy/)

It generates a complete .rego file, saves it to the right location, and validates the syntax — no Rego knowledge required.

VS Code tip: If manage_todo_list and vscode_askQuestions are available, the tool uses them for interactive progress tracking and selection prompts.

Quickstart - Manual

1. Create a directory for your policies and add a .rego file:

mkdir -p ~/.config/containerization-assist/policies

2. Save a policy file to that directory, e.g. ~/.config/containerization-assist/policies/require-mcr-images.rego:

# Rego policy: block Dockerfiles that use base images outside mcr.microsoft.com
package containerization.require_mcr

# Extract all FROM lines from the Dockerfile
from_lines := [line |
  line := split(input.content, "\n")[_]
  startswith(trim_space(line), "FROM ")
]

# Flag each FROM line that does not reference mcr.microsoft.com
violations contains result if {
  some line in from_lines
  not contains(line, "mcr.microsoft.com/")

  result := {
    "rule": "require-mcr-images",
    "category": "security",
    "priority": 95,
    "severity": "block",
    "message": sprintf("Base image must come from mcr.microsoft.com: %s", [trim_space(line)]),
  }
}

default allow := false
allow if count(violations) == 0
result := { "allow": allow, "violations": violations }

3. Point the server to your policies directory in .vscode/mcp.json:

{
  "servers": {
    "containerization-assist": {
      "env": {
        "CUSTOM_POLICY_PATH": "${env:HOME}/.config/containerization-assist/policies"
      }
    }
  }
}

4. Policies are auto-reloaded on the next tool execution — no restart needed.

Policy Priority

Policies are discovered and merged from four locations in priority order:

1. Built-in policies/ (lowest priority) - Base security and quality rules
2. ~/.config/containerization-assist/policy/ (low-medium priority) - Global user customizations
3. <git-root>/.containerization-assist/policy/ (medium-high priority) - Project-specific policies
4. CUSTOM_POLICY_PATH environment variable (highest priority) - Custom location

Later policies override earlier policies by package namespace.

Common Use Cases

Allow All Container Registries

Override built-in MCR preference to allow Docker Hub, GCR, ECR, etc.

# From npm package
cp node_modules/containerization-assist-mcp/policies.user.examples/allow-all-registries.rego \
   .containerization-assist/policy/
# Policies are auto-reloaded on the next tool execution — no restart needed

Advisory-Only Mode

Convert all blocking violations to warnings for testing or development.

# From npm package
cp node_modules/containerization-assist-mcp/policies.user.examples/warn-only-mode.rego \
   .containerization-assist/policy/
# Policies are auto-reloaded on the next tool execution — no restart needed

Organization-Specific Rules

Create custom policies for your organization's requirements.

# From npm package
cp node_modules/containerization-assist-mcp/policies.user.examples/custom-organization-template.rego \
   .containerization-assist/policy/my-org-policy.rego
# Edit my-org-policy.rego to customize
# Policies are auto-reloaded on the next tool execution — no restart needed

Testing Your Policies

1. List Discovered Policies

# List all discovered policies
npx containerization-assist-mcp list-policies

# Show merged policy result
npx containerization-assist-mcp list-policies --show-merged

2. Check Discovery Logs

npx containerization-assist-mcp start --log-level debug 2>&1 | grep -i policy

Look for:

Discovered built-in policies: 3 files
Discovered project policies from .containerization-assist/policy/: 1 files

3. Test with Dockerfile Validation

echo 'FROM node:latest\nUSER root' > test.Dockerfile
# Use fix-dockerfile tool via your MCP client

Troubleshooting

Q: My custom policy isn't loading

Check file extension (must be .rego):

ls -la .containerization-assist/policy/
# ✅ my-policy.rego
# ❌ my-policy.rego.txt or my-policy.yaml

Check discovery logs:

npx containerization-assist-mcp list-policies

Q: Built-in policies still blocking

Custom policies override by package namespace. See the allow-all-registries.rego example in policies.user.examples/ for how to override built-in rules.

Q: Changes not taking effect

Policy file changes (additions, edits, deletions) are picked up automatically on the next tool execution — no restart needed. Restart is only required for environment variable or transport configuration changes.

Q: Syntax error in my policy

Validate policy syntax:

opa check .containerization-assist/policy/my-policy.rego
opa test .containerization-assist/policy/

Reverting to Built-In Policies

# Remove project policies
rm -rf .containerization-assist/policy/

# Or remove global policies
rm -rf ~/.config/containerization-assist/policy/

# Remove environment variable from .vscode/mcp.json if set
# Restart only needed for env var or transport config changes (not policy file changes)

Support

• Policy Customization Examples (also available at node_modules/containerization-assist-mcp/policies.user.examples/)
• OPA Rego Documentation
• GitHub Issues