{"id":17925955,"url":"https://github.com/shoenig/nomad-pledge-driver","last_synced_at":"2026-01-30T04:43:15.824Z","repository":{"id":56865521,"uuid":"514435608","full_name":"shoenig/nomad-pledge-driver","owner":"shoenig","description":"Nomad task driver capable of blocking unwanted syscall and filesystem access. Based on the pledge utility for Linux by Justine Tunney","archived":false,"fork":false,"pushed_at":"2024-04-01T05:03:53.000Z","size":415,"stargazers_count":22,"open_issues_count":8,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-09T01:50:10.461Z","etag":null,"topics":["golang","isolation","linux","nomad","pledge","sandbox","task-driver","unveil"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shoenig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-07-16T00:07:22.000Z","updated_at":"2024-06-05T21:45:28.000Z","dependencies_parsed_at":"2024-01-02T16:32:27.770Z","dependency_job_id":"683ebba6-41f4-4241-917e-55d73b98bb6e","html_url":"https://github.com/shoenig/nomad-pledge-driver","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shoenig%2Fnomad-pledge-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shoenig%2Fnomad-pledge-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shoenig%2Fnomad-pledge-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shoenig%2Fnomad-pledge-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shoenig","download_url":"https://codeload.github.com/shoenig/nomad-pledge-driver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240831380,"owners_count":19864718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","isolation","linux","nomad","pledge","sandbox","task-driver","unveil"],"created_at":"2024-10-28T20:58:31.942Z","updated_at":"2026-01-30T04:43:15.798Z","avatar_url":"https://github.com/shoenig.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nomad-pledge-driver\n\n![GitHub](https://img.shields.io/github/license/shoenig/nomad-pledge-driver?style=flat-square)\n[![Run E2E Tests](https://github.com/shoenig/nomad-pledge-driver/actions/workflows/e2e.yaml/badge.svg)](https://github.com/shoenig/nomad-pledge-driver/actions/workflows/e2e.yaml)\n\n`nomad-pledge-driver` is a Nomad task driver based on the `pledge` [utility for Linux](https://justine.lol/pledge/) by Justine Tunney.\n\n*Security through SECCOMP sorcery*\n\n### Features\n\n- Sandbox applications by **restricting syscalls** they are able to make (via _promises_)\n- Sandbox applications by **allow-listing filepaths** they are allowed to access (via _unveil_)\n- Sandbox applications by **restricting resources** using modern Linux cgroups (via _cgroups v2_)\n- Sandbox applications by **namespace isolation** using Linux namespaces (via _nsenter_ and _unshare_)\n\n### Use cases\n\nThe `nomad-pledge-driver` is intended as a replacement for `raw_exec`. Sometimes\nthere are those management tasks that just need to run as `root` and directly\naccess the filesystem or perform privileged operations. While `raw_exec`\nprovides no isolation, the `pledge` driver uses Landlock to restrict the files\nor directories the task is allowed to access. Specific groups of system calls\nare allow-listed, greatly  reducing the attack surface of a mis- configured or\ncompromised task.\n\n### Compatability\n\n- Use version 0.3 with Nomad 1.7 and higher\n- Use version 0.2 for Nomad 1.6 and below\n  \n### Examples\n\nThe example below uses `curl` to fetch `example.com`, with the minimal set of promises to make a request.\n\nMore complex examples in the [hack](hack) directory.\n\n```hcl\njob \"curl\" {\n  type        = \"batch\"\n\n  group \"group\" {\n    task \"curl\" {\n      driver = \"pledge\"\n      config {\n        command  = \"curl\"\n        args     = [\"example.com\"]\n        promises = \"stdio rpath inet dns sendfd\"\n        unveil   = [\"r:${NOMAD_TASK_DIR}\"]\n      }\n    }\n  }\n}\n```\n\n### Building\n\nThe `nomad-pledge-driver` plugin is written in Go. It can be built using the normal Go toolchain steps, but\nthe Makefile contains a `dev` target to make things easy. The compiled binary will appear in the `output/`\ndirectory.\n\n```shell\nmake dev\n```\n\n### Installing \n\nThe plugin should be placed in the `plugin_dir` configured by the Nomad agent, per Nomad's [documentation](https://www.nomadproject.io/docs/configuration#plugin_dir).\n\nYou'll also need the `pledge` executable (1.8 or higher) that powers the plugin sandboxing.\nDownload the `pledge` executable from https://justine.lol/pledge/ and install it somewhere.\nThe plugin configuration lets you specify where the path to the pledge executable.\n\n```shell\nsudo mkdir -p /opt/bin\ncurl -L -o /opt/bin/pledge-1.8.com https://justine.lol/pledge/pledge-1.8.com\n```\n\n:point_right: **optional** It is very convenient to bless the pledge executable with the `cap_net_bind_service`\nLinux capability. This will enable Nomad tasks using the pledge driver to bind to privileged\nports (e.g. below 1024).\n\n```shell\nsudo setcap cap_net_bind_service+eip /opt/bin/pledge-1.8.com\n```\n\nThe plugin will expose the `driver.pledge.cap.net_bind` attribute indicating whether\nthe `cap_net_bind_service` capability has been set on the `pledge-1.x.com` executable.\n\n### Plugin Configuration\n\nCurrently there is only one configuration option for this plugin, which is to specify the path of the `pledge` executable.\n\n```hcl\nplugin \"nomad-pledge-driver\" {\n  config {\n    pledge_executable = \"/opt/bin/pledge-1.8.com\"\n  }\n}\n```\n\nNote: in these examples the driver plugin is named `pledge`, and the utility executable is named `pledge-1.8.com`. \n\n### Task Configuration\n\nTasks need to specify which **promises** they require in order to run.\n\nTasks also need to **unveil** the filesystem paths needed to run.\n\nFor more information about which pledges are available and how this mechanism works, visit https://justine.lol/pledge/\n\nIf no `user` is specified for the task, the pledge plugin will use the user of\nthe Nomad client by default. Like the `raw_exec` task driver, `user` cannot be\nset in hardened clusters according to the [production guide](https://developer.hashicorp.com/nomad/docs/install/production/requirements#user-permissions).\n\n- `command`: The executable to run\n- `args`: The arguments to pass to executable\n- `promises`: The set of promises needed for the executable to run\n- `unveil`: The set of system filepaths to allow the task to access, and with what permission\n- `importance`: One of `lowest`, `low`, `normal`, `high`, `highest` (default is `normal`)\n\n```hcl\n# see hack/http.hcl for complete python http.server example\n# note that bridge mode also works, see hack/bridge.hcl\n\ntask \"task\" {\n  driver = \"pledge\"\n  user   = \"nobody\"\n  config {\n    command    = \"python3\"\n    args       = [\"-m\", \"http.server\", \"${NOMAD_PORT_http}\", \"--directory\", \"${NOMAD_TASK_DIR}\"]\n    promises   = \"stdio rpath inet\"\n    unveil     = [\"r:/etc/mime.types\", \"r:${NOMAD_TASK_DIR}\"]\n    importance = \"low\"\n  }\n\n  template {\n    destination = \"local/index.html\"\n    data        = \u003c\u003cEOH\n\u003c!doctype html\u003e\n\u003chtml\u003e\n  \u003ctitle\u003eexample\u003c/title\u003e\n  \u003cbody\u003e\u003cp\u003eHello, friend!\u003c/p\u003e\u003c/body\u003e\n\u003c/html\u003e\nEOH\n  }\n}\n```\n\n### Troubleshooting\n\nFor help getting the plugin to work, see the [TROUBLESHOOT](TROUBLESHOOT.md) doc.\nOtherwise feel free to file an issue!\n\n### Contributing\n\nThe `nomad-pledge-driver` plugin is currently under active development - anything may change at a moments notice!\n\n#### hacking\n\nThe included Makefile includes helpful targets for hacking on the pledge plugin.\n\nTo simply compile, run `make dev`. The output will go into `/tmp/plugins`.\n\nTo start Nomad with the plugin, run `make run`. Under the hood this is using the `hack/client.hcl` Client\nconfig file, along with `-dev` mode defaults. You should be able to run jobs making use of `pledge` driver\nwhen launching Nomad this way.\n\nThere are example jobs in the [hack/](hack) directory.\n\n### License\n\nThe `pledge` task driver plugin is made open source under the [MPL-2.0](LICENSE) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshoenig%2Fnomad-pledge-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshoenig%2Fnomad-pledge-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshoenig%2Fnomad-pledge-driver/lists"}