Skip to content

README.md

Latest commit

 

History

History
486 lines (350 loc) · 12 KB

README.md

File metadata and controls

486 lines (350 loc) · 12 KB

Seccomp Profiles

Syscall Filtering and Attack Surface Reduction

A comprehensive collection of seccomp-bpf (Berkeley Packet Filter) profiles and tooling for reducing attack surface by filtering system calls. Provides pre-built profiles for common security scenarios and a framework for creating custom syscall filters.

Overview

seccomp-profiles enables fine-grained control over which system calls a process can execute, dramatically reducing the attack surface of applications. By whitelisting only necessary syscalls, you can prevent entire classes of exploits.

Features

Pre-Built Profiles

  • strict: Minimal syscall set for computation-only workloads
  • web-server: Profile optimized for HTTP/HTTPS servers
  • database: Profile for database engines
  • build-tools: Profile for compilers and build systems
  • container-runtime: Profile for container execution environments
  • nodejs: Profile for Node.js applications
  • python: Profile for Python interpreters
  • general: Balanced profile for general-purpose applications

Tooling

  • Profile Generator: Create custom profiles from syscall traces
  • Profile Validator: Verify profile correctness and security
  • Profile Analyzer: Analyze attack surface reduction metrics
  • Profile Merger: Combine multiple profiles intelligently
  • Runtime Tracer: Capture syscalls from running processes

Advanced Features

  • Architecture Support: x86_64, ARM64, ARM, x86
  • Kernel Version Detection: Automatic feature detection
  • Error Handling: Configurable actions (KILL, TRAP, ERRNO, LOG)
  • Argument Filtering: Filter based on syscall arguments
  • Conditional Filters: Dynamic filters based on process state

Architecture

┌─────────────────────────────────────────────┐
│         Application Layer                   │
│  (Your code using seccomp-profiles)         │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│     Profile Management API                  │
│  - Profile Loader                           │
│  - Profile Compiler                         │
│  - Profile Applicator                       │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│     BPF Program Generator                   │
│  - Syscall Filter Rules                     │
│  - Argument Matchers                        │
│  - Action Handlers                          │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│      Linux Seccomp Interface                │
│  - prctl(PR_SET_SECCOMP)                    │
│  - seccomp(2) syscall                       │
└─────────────────────────────────────────────┘

Installation

As a Git Submodule

git submodule add https://github.com/navinBRuas/_SecureExecutionEnvironment.git vendor/secure-execution
cd vendor/secure-execution/seccomp-profiles
make

As a System Library

make install PREFIX=/usr/local

Quick Start

Using Pre-Built Profiles (C)

#include <seccomp-profiles/profile.h>

int main() {
    // Load a pre-built profile
    seccomp_profile_t *profile = seccomp_profile_load("strict.json");
    if (!profile) {
        fprintf(stderr, "Failed to load profile\n");
        return 1;
    }
    
    // Apply the profile to current process
    if (seccomp_profile_apply(profile, SECCOMP_ACTION_KILL) != 0) {
        fprintf(stderr, "Failed to apply profile\n");
        return 1;
    }
    
    // From this point, only allowed syscalls work
    printf("Seccomp profile applied successfully\n");
    
    // Clean up
    seccomp_profile_free(profile);
    
    return 0;
}

Creating Custom Profiles (JSON)

{
  "name": "my-application",
  "version": "1.0",
  "arch": ["x86_64", "aarch64"],
  "default_action": "SCMP_ACT_ERRNO",
  "syscalls": {
    "allow": [
      "read",
      "write",
      "open",
      "close",
      "stat",
      "fstat",
      "lstat",
      "mmap",
      "munmap",
      "brk",
      "exit",
      "exit_group"
    ],
    "conditional": [
      {
        "name": "ioctl",
        "args": [
          {"index": 1, "op": "==", "value": "FIONREAD"}
        ]
      }
    ]
  }
}

Python API

from seccomp_profiles import Profile, Action

# Load profile
profile = Profile.load('strict.json')

# Apply to current process
profile.apply(default_action=Action.KILL)

# Or apply to a subprocess
import subprocess
profile.apply_to_subprocess(['/bin/ls', '-la'])

Profile Reference

Strict Profile

Minimal syscall set for pure computation. No filesystem, network, or IPC access.

Allowed syscalls: read, write, brk, mmap, munmap, mprotect, exit, exit_group

Use cases:

  • Mathematical computations
  • Data transformations
  • Cryptographic operations
  • Sandboxed code execution

Web Server Profile

Optimized for HTTP/HTTPS server processes.

Key features:

  • Socket operations (bind, listen, accept, send, recv)
  • File serving (open, read, stat)
  • No process creation
  • No ptrace/debugging capabilities

Use cases:

  • Nginx workers
  • Apache workers
  • Node.js HTTP servers
  • Python WSGI applications

Database Profile

Profile for database engine processes.

Key features:

  • File I/O operations
  • Memory management
  • Shared memory (IPC)
  • No network operations (assumes local socket)

Use cases:

  • PostgreSQL
  • MySQL/MariaDB
  • SQLite
  • Redis

API Reference

Profile Loading

seccomp_profile_load(path)

Load a profile from a JSON file.

seccomp_profile_parse(json_string)

Parse a profile from a JSON string.

seccomp_profile_load_builtin(name)

Load a pre-built profile by name.

Profile Application

seccomp_profile_apply(profile, default_action)

Apply profile to the current process.

Actions:

  • SECCOMP_ACTION_KILL - Kill process on violation
  • SECCOMP_ACTION_TRAP - Send SIGSYS on violation
  • SECCOMP_ACTION_ERRNO - Return errno on violation
  • SECCOMP_ACTION_TRACE - Notify tracer on violation
  • SECCOMP_ACTION_LOG - Log violation and allow

seccomp_profile_apply_to_child(profile, pid)

Apply profile to a child process (requires ptrace).

Profile Creation

seccomp_profile_new(name)

Create a new empty profile.

seccomp_profile_add_syscall(profile, name)

Add a syscall to the allow list.

seccomp_profile_add_syscall_with_args(profile, name, args)

Add a syscall with argument filtering.

seccomp_profile_save(profile, path)

Save profile to a JSON file.

Analysis Tools

seccomp_analyze_trace(trace_file)

Analyze a syscall trace and suggest a profile.

seccomp_profile_diff(profile1, profile2)

Compare two profiles and show differences.

seccomp_profile_validate(profile)

Validate profile for correctness and security.

Tooling

Trace Generator

Capture syscalls from a running process:

# Trace a command
seccomp-trace /path/to/program args

# Generate profile from trace
seccomp-trace --generate-profile output.json /path/to/program args

Profile Analyzer

Analyze attack surface reduction:

seccomp-analyze profiles/strict.json

# Output:
# Profile: strict
# Syscalls allowed: 12 / 334 (3.6%)
# Attack surface reduction: 96.4%
# Risk categories blocked:
#   - Process creation: ✓
#   - Network operations: ✓
#   - File system modification: ✓
#   - Privilege escalation: ✓

Profile Validator

seccomp-validate profiles/my-app.json

# Checks:
# - JSON syntax
# - Syscall name validity
# - Argument filter correctness
# - Architecture compatibility
# - Security best practices

Integration Examples

With process-sandbox

#include <process-sandbox/sandbox.h>
#include <seccomp-profiles/profile.h>

sandbox_config_t config = sandbox_config_new();
seccomp_profile_t *profile = seccomp_profile_load("web-server.json");

// Apply seccomp filter after sandbox creation
int apply_seccomp(void *arg) {
    seccomp_profile_t *profile = (seccomp_profile_t *)arg;
    return seccomp_profile_apply(profile, SECCOMP_ACTION_KILL);
}

sandbox_config_set_pre_exec_callback(&config, apply_seccomp, profile);
sandbox_exec(&config, "/usr/sbin/nginx", argv, NULL);

With Docker/Podman

# Use as Docker seccomp profile
docker run --security-opt seccomp=profiles/web-server.json nginx

With systemd

[Service]
ExecStart=/usr/bin/myapp
SystemCallFilter=@/path/to/seccomp-profiles/strict.json
SystemCallErrorNumber=EPERM

Building

Requirements

  • Linux kernel 3.5+ (seccomp-bpf support)
  • libseccomp-dev
  • GCC 9+ or Clang 10+
  • Python 3.7+ (for tooling)

Build Commands

# Build library
make

# Build tools
make tools

# Run tests
make test

# Install
sudo make install

Profile Development Guide

Step 1: Trace Your Application

seccomp-trace --output trace.log ./myapp --my-args

Step 2: Generate Initial Profile

seccomp-generate --input trace.log --output myapp.json

Step 3: Review and Refine

seccomp-validate myapp.json
seccomp-analyze myapp.json

Step 4: Test

seccomp-test myapp.json ./myapp --my-args

Step 5: Deploy

sudo cp myapp.json /etc/seccomp-profiles/

Security Best Practices

  1. Start Strict: Begin with the strictest profile that works
  2. Iterate: Add syscalls only as needed
  3. Use Argument Filters: Restrict syscall arguments when possible
  4. Default Deny: Always use deny-by-default with allowlists
  5. Test Thoroughly: Test all application paths
  6. Monitor Violations: Log and monitor seccomp violations in production
  7. Version Profiles: Keep profiles in version control
  8. Regular Audits: Review and update profiles regularly

Performance Considerations

  • Overhead: <1% CPU overhead for most workloads
  • Memory: ~4KB per profile loaded
  • Filter Complexity: Linear search through rules (keep profiles concise)
  • Argument Filters: Add minimal overhead (~10 ns per check)

Troubleshooting

Application crashes with SIGSYS

The application is attempting a blocked syscall. Use the tracer to identify:

seccomp-trace --identify-violation ./myapp

Profile doesn't load

Validate profile syntax:

seccomp-validate myapp.json

Performance degradation

Check filter complexity:

seccomp-analyze --performance myapp.json

Contributing

See CONTRIBUTING.md

License

MIT License - See LICENSE

References

Standalone Installation

git submodule add https://github.com/navinBRuas/_SecureExecutionEnvironment.git vendor/secure-execution

Use vendor/secure-execution/seccomp-profiles for local builds and integration.

Usage

Follow the C and Python examples above and module tooling for profile generation.

Configuration

Profiles are configured via JSON files and applied through the seccomp profile API.

Version

Current version: 0.1.0 (see VERSION.md).

Changelog

See CHANGELOG.md for release history.