Dynamic AppArmor Profile Management for Kubernetes

Kapparmor is a cloud-native security enforcer that simplifies AppArmor profile management in Kubernetes clusters. Deploy, update, and manage AppArmor security profiles across your infrastructure through a simple ConfigMap interface—no manual node configuration required.

• Why AppArmor?
  • AppArmor vs SELinux vs Seccomp
• Key Features
• Security-First Approach
• Getting Started
  • Prerequisites
  • Installation
    • Via Helm (Recommended)
    • Via kubectl (Manual)
  • Quick Start
• Architecture
  • How It Works
  • Component Diagram
• Configuration
  • Environment Variables / Helm Values
  • Helm Chart Values Example
• Constraints & Limitations
• Testing
• Documentation
  • 📚 Available Documentation
  • 🔗 External References
  • 📖 Learning Resources
• Release Process
• Contributing
• Community & Support
• License
• Credits & Acknowledgments

Kapparmor dynamically loads and unloads AppArmor security profiles on Kubernetes cluster nodes via ConfigMap. It runs as a privileged DaemonSet on Linux nodes, eliminating the need for manual profile management on each node.

Key Capabilities:

• 🔄 Dynamic Loading – Apply profile changes without node restarts
• 📦 ConfigMap-Based – Version control your security policies as Kubernetes manifests
• 🧹 Auto-Cleanup – Automatically remove unused profiles
• 🔍 Change Detection – Detects and syncs profile modifications
• ✅ Validation – Validates syntax before kernel loading
• 📊 Observable – Health endpoints and structured logging

This work was inspired by kubernetes/apparmor-loader.

Choose AppArmor when you need:

• Easy-to-understand security profiles
• File and path-level access control
• Capability restrictions
• Port binding restrictions
• Network namespace access control

Choose SELinux when you need:

• Label-based context systems
• Enterprise policy frameworks (CIS profiles)
• Existing infrastructure investment

Choose Seccomp when you need:

• Only syscall filtering
• Lightweight containerized defaults
• Minimal overhead for simple restrictions

🔐 Enterprise-Grade Security

• Input validation with fuzz testing
• Secure coding practices (SSDLC)
• Supply chain security (signed commits, Harden-Runner, CodeQL)
• Zero external runtime dependencies

⚡ Kubernetes-Native

• DaemonSet-based deployment
• ConfigMap-driven configuration
• Health checks and readiness probes
• Optional Prometheus metrics

🛡️ Robust Profile Management

• Syntax validation before loading
• Filename/profile name consistency checks
• Path traversal protection
• Automatic cleanup of orphaned profiles

📈 Production-Ready

• Comprehensive test coverage
• CI/CD security gates
• OpenSSF Best Practices certified
• No privileged escalation vectors

Kapparmor is built with security as a core principle:

✅ Threat Modeling – Comprehensive STRIDE analysis
✅ Code Quality – 80%+ test coverage, zero high-severity CodeQL alerts
✅ Supply Chain – Pinned dependencies, signed commits, SBOM tracking
✅ Vulnerability Scanning – Trivy, Gosec, Snyk integration
✅ Least Privilege – Minimal RBAC, no elevated capabilities unless required

👉 Read the full security threat model for detailed analysis of risks and mitigations.

System Requirements:

• Kubernetes 1.23+
• Ubuntu 22.04+ or similar Debian-based Linux nodes
• AppArmor enabled on all nodes:

  cat /sys/module/apparmor/parameters/enabled
  # Output should be: Y

• Helm 3.0+ (for easy installation)

Verify AppArmor is enabled:

# On each node
sudo aa-status

# Expected output shows: "X profiles loaded" and "X processes are in enforce/complain mode"

# Install directly from ghcr.io (no helm repo add needed)
helm upgrade kapparmor --install \
  --namespace kube-system \
  --atomic \
  --timeout 120s \
  oci://ghcr.io/tuxerrante/charts/kapparmor

# Or customize values
helm upgrade kapparmor --install \
  --namespace kube-system \
  --set image.tag=v1.0.0 \
  --set app.pollTime=30 \
  oci://ghcr.io/tuxerrante/charts/kapparmor --version 0.3.1

# Add the Kapparmor Helm repository
helm repo add tuxerrante https://tuxerrante.github.io/kapparmor
helm repo update

# Install with defaults
helm upgrade kapparmor --install \
  --namespace kube-system \
  --atomic \
  --timeout 120s \
  tuxerrante/kapparmor

kubectl apply -f https://github.com/tuxerrante/kapparmor/releases/download/v1.0.0/kapparmor-manifest.yaml

1. Create an AppArmor profile ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: kapparmor-profiles
  namespace: kube-system
data:
  custom.deny-write-outside-home: |
    #include <tunables/global>
    
    profile custom.deny-write-outside-home flags=(attach_disconnected,mediate_deleted) {
      #include <abstractions/base>
      
      capability setuid,
      capability setgid,
      capability dac_override,
      
      /home/** rw,
      /tmp/** rw,
      /var/tmp/** rw,
      
      deny /etc/** w,
      deny /root/** w,
      deny / w,
    }

2. Apply the ConfigMap:

kubectl apply -f apparmor-profiles.yaml

3. Deploy workload with the profile:

apiVersion: v1
kind: Pod
metadata:
  name: secure-app
  annotations:
    container.apparmor.security.beta.kubernetes.io/app: localhost/custom.deny-write-outside-home
spec:
  containers:
  - name: app
    image: ubuntu:24.04
    command: ["/bin/bash", "-c", "sleep infinity"]

4. Verify profile was loaded:

# Check on the node
sudo aa-status | grep custom.deny-write-outside-home

# Or from the pod
kubectl logs -n kube-system -l app=kapparmor | grep "Profile.*loaded"

1. Polling – Every POLL_TIME seconds (default: 30s), Kapparmor checks the kapparmor-profiles ConfigMap
2. Comparison – Identifies new, modified, or deleted profiles by comparing with local state
3. Validation – Validates profile syntax before kernel loading:
   • Profile name must start with custom.
   • Filename must match profile name
   • Must contain profile keyword and opening brace {
   • Path traversal checks on filename
4. Loading – Executes apparmor_parser --replace <profile> for new/updated profiles
5. Unloading – Executes apparmor_parser --remove <profile> for deleted profiles
6. Cleanup – Removes profile files from /etc/apparmor.d/custom/

┌──────────────────────────────────────┐
│   Kubernetes Control Plane           │
│  (ConfigMap: kapparmor-profiles)     │
└────────────┬─────────────────────────┘
             │
             │ (mount via volume)
             ▼
┌──────────────────────────────────────┐
│   Kapparmor DaemonSet Pod            │
│  ┌────────────────────────────────┐  │
│  │ Poll ConfigMap every 30s       │  │
│  │ Validate profiles              │  │
│  │ Copy to /etc/apparmor.d/custom │  │
│  │ Execute apparmor_parser        │  │
│  └────────────────────────────────┘  │
└────────────┬─────────────────────────┘
             │
             │ (apparmor_parser binary)
             ▼
┌──────────────────────────────────────┐
│   Host Linux Kernel                  │
│  (AppArmor module)                   │
│  /sys/kernel/security/apparmor/      │
└──────────────────────────────────────┘

# values.yaml
app:
  pollTime: 30
  configmapPath: /app/profiles
  profilesDir: /etc/apparmor.d/custom
  logLevel: "INFO"

image:
  repository: ghcr.io/tuxerrante/kapparmor
  tag: "v1.0.0"
  pullPolicy: IfNotPresent

resources:
  limits:
    cpu: 200m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 64Mi

nodeSelector:
  kubernetes.io/os: linux

⚠️ Important:

1. Profile Naming – Custom profiles MUST start with custom. prefix and match the filename

   ❌ BAD:  myprofile (missing prefix)
   ✅ GOOD: custom.myprofile (filename must also be custom.myprofile)
   

2. Profile Syntax – Profiles must be valid AppArmor syntax:

   ✅ REQUIRED: profile custom.name { ... }
   ❌ NOT SUPPORTED: hat name { ... } (nested profiles)
   

3. Polling Interval – Must be between 1 and 86400 seconds (24 hours)

4. Node State – Start on clean nodes (remove old orphaned profiles first)

   # Cleanup before initial deployment
   sudo rm -f /etc/apparmor.d/custom/*
   sudo systemctl reload apparmor

5. Pod Dependencies – Always delete pods using a profile before removing the profile from ConfigMap

   # BAD: This can crash Kapparmor
   kubectl delete configmap kapparmor-profiles
   
   # GOOD: Delete pods first
   kubectl delete pod -l app-profile=myprofile
   kubectl patch configmap kapparmor-profiles --type json -p='[{"op":"remove","path":"/data/custom.myprofile"}]'

Comprehensive testing is documented in docs/testing.md.

Quick test:

# Run Go tests
make test

# Run security checks
make lint

# Deploy to local MicroK8s cluster (if available)
./build/test_on_microk8s.sh

See the KAppArmor Demo project for practical examples.

• Kubernetes AppArmor Tutorial – Official K8s guide
• AppArmor Documentation – Ubuntu reference
• AppArmor Profile Reference – Complete profile syntax
• AppArmor Profiles – SUSE documentation

• AppArmor Profiles are easier to learn than SELinux policies and more flexible than Seccomp
• Start with simple restrictive profiles (deny certain paths/capabilities)
• Use complain mode for testing before enabling enforce mode
• The included sample profiles are good starting points

1. ✏️ Update config/config with new versions (app, chart, Go)
2. ✏️ Update charts/kapparmor/Chart.yaml with matching version
3. 🧪 Run unit and integration tests (see Makefile)
4. ✏️ Update charts/kapparmor/CHANGELOG.md
5. 📝 Open PR, get reviews
6. ✅ Merge to main
7. 🏷️ Create signed Git tag: git tag -s v1.0.0
8. 🚀 GitHub Actions automatically builds and publishes

Note: Commits must be signed (git config commit.gpgsign true)

Contributions are welcome! Please read CONTRIBUTING.md for:

• How to report bugs and request features
• How to set up a development environment
• Coding standards and testing requirements
• The pull request process

This project follows the Contributor Covenant Code of Conduct.

For security vulnerabilities, see SECURITY.md.

• 🐛 Found a bug? Open an issue
• 💡 Feature request? Start a discussion
• 📚 Need help? Check the docs
• 📋 Changelog: See CHANGELOG.md for release history

This project is licensed under the Apache 2.0 License.

• 🎨 Logo design by @Noblesix960
• 📝 Inspired by kubernetes/apparmor-loader
• 🔐 Security guidance from Microsoft SDL and OWASP
• ☁️ Cloud-native architecture patterns from CNCF ecosystem

Made with ❤️ for cloud-native security