Skip to content

QUICKSTART.md

Latest commit

 

History

History
124 lines (94 loc) · 3.42 KB

QUICKSTART.md

File metadata and controls

124 lines (94 loc) · 3.42 KB
Raw

SEChrome Quickstart (Docker)

This quickstart provides a reproducible Docker environment that builds secure_chrome_launcher and runs Chromium under SEChrome policies.

Build the image

From the SEChrome/ directory:

docker build -t sechrome:dev -f docker/Dockerfile .

If you are in mainland China, use a closer Debian mirror to speed up the Chromium install step (pick one):

# Aliyun
docker build -t sechrome:dev -f docker/Dockerfile . \
  --build-arg APT_MIRROR=mirrors.aliyun.com \
  --build-arg APT_SECURITY_MIRROR=mirrors.aliyun.com
# TUNA (Tsinghua)
docker build -t sechrome:dev -f docker/Dockerfile . \
  --build-arg APT_MIRROR=mirrors.tuna.tsinghua.edu.cn \
  --build-arg APT_SECURITY_MIRROR=mirrors.tuna.tsinghua.edu.cn
# USTC
docker build -t sechrome:dev -f docker/Dockerfile . \
  --build-arg APT_MIRROR=mirrors.ustc.edu.cn \
  --build-arg APT_SECURITY_MIRROR=mirrors.ustc.edu.cn

Also consider configuring a Docker registry mirror to speed up pulling base images (one-time on the host):

Create /etc/docker/daemon.json:

{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://docker.mirrors.ustc.edu.cn"
  ]
}

Then restart Docker:

sudo systemctl restart docker

Verify the image

After building, you can verify the image works correctly:

./docker/test_docker.sh

This will run automated tests to ensure:

  • The image can successfully fetch and dump web pages
  • The launcher binary exists and is executable
  • The configuration file is present

Run (ptrace mode, recommended for quickstart)

Ptrace inside Docker typically requires:

  • SYS_PTRACE
  • an unconfined Docker seccomp profile (otherwise ptrace is often blocked)
docker run --rm -it \
  --cap-add=SYS_PTRACE \
  --security-opt seccomp=unconfined \
  --shm-size=1g \
  sechrome:dev \
  --config=/app/docker/config.docker.yaml -- --dump-dom https://example.com

Security note for container configs:

  • The included docker/config.docker.yaml is designed to avoid whitelisting /home.
  • The image runs as a non-root user with HOME and XDG_CONFIG_HOME redirected under /tmp, so Chrome writes stay under /tmp (which is already the intended write scope).

Run (seccomp-notify mode)

Seccomp user-notify typically requires:

  • SYS_ADMIN
  • an unconfined Docker seccomp profile (or a custom profile that allows seccomp())
docker run --rm -it \
  --cap-add=SYS_ADMIN \
  --security-opt seccomp=unconfined \
  --shm-size=1g \
  sechrome:dev \
  --config=/app/docker/config.docker.yaml -- --dump-dom https://example.com

Then edit /app/docker/config.docker.yaml in the image or mount your own config and set:

  • security.seccomp_notify: true
  • security.ptrace_enabled: false

Use your own config

Mount a config from the host:

docker run --rm -it \
  --cap-add=SYS_PTRACE \
  --security-opt seccomp=unconfined \
  --shm-size=1g \
  -v "$PWD/docker/config.docker.yaml:/app/config.yaml:ro" \
  sechrome:dev \
  --config=/app/config.yaml -- --dump-dom https://example.com

Troubleshooting

  • If Chromium fails to start, inspect /tmp/sechrome_audit.log (inside the container) and widen rules minimally.
  • If you see Operation not permitted for ptrace: ensure --cap-add=SYS_PTRACE and --security-opt seccomp=unconfined.
  • If seccomp-notify cannot initialize: ensure --cap-add=SYS_ADMIN and --security-opt seccomp=unconfined.