-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: grantseltzer <[email protected]>
- Loading branch information
1 parent
c4fda4f
commit e34b254
Showing
90 changed files
with
2,906 additions
and
6,143 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,137 +1,12 @@ | ||
| # Set an output prefix, which is the local directory if not specified | ||
| PREFIX?=$(shell pwd) | ||
| default: karn-cli | ||
|
|
||
| # Setup name variables for the package/tool | ||
| NAME := karn | ||
| PKG := github.com/grantseltzer/$(NAME) | ||
| .PHONY: karn-cli | ||
| karn-cli: | ||
| mkdir -p ./bin | ||
| go build -o ./bin/karn ./cmd/cli | ||
|
|
||
| # Set the build dir, where built cross-compiled binaries will be output | ||
| BUILDDIR := ${PREFIX}/cross | ||
| clean: | ||
| rm ./bin/* | ||
|
|
||
| # The location of the original declarations | ||
| DECLARATIONDIR := ${PREFIX}/declarations | ||
|
|
||
| # Set default declaration dir | ||
| INSTALLDECLARATIONS := ~/.karn/ | ||
|
|
||
| # Populate version variables | ||
| # Add to compile time flags | ||
| VERSION := $(shell cat VERSION) | ||
| GITCOMMIT := $(shell git rev-parse --short HEAD) | ||
| GITUNTRACKEDCHANGES := $(shell git status --porcelain --untracked-files=no) | ||
| ifneq ($(GITUNTRACKEDCHANGES),) | ||
| GITCOMMIT := $(GITCOMMIT)-dirty | ||
| endif | ||
| CTIMEVAR=-X $(PKG)/version.GITCOMMIT=$(GITCOMMIT) -X $(PKG)/version.VERSION=$(VERSION) | ||
| GO_LDFLAGS=-ldflags "-w $(CTIMEVAR)" | ||
| GO_LDFLAGS_STATIC=-ldflags "-w $(CTIMEVAR) -extldflags -static" | ||
|
|
||
| # List the GOOS and GOARCH to build | ||
| GOOSARCHES = darwin/amd64 darwin/386 freebsd/amd64 freebsd/386 linux/arm linux/arm64 linux/amd64 linux/386 solaris/amd64 windows/amd64 windows/386 | ||
|
|
||
| all: bindata build fmt lint vet ## runs a clean, build, fmt, lint, test, vet and install | ||
|
|
||
| .PHONY: build | ||
| build: $(NAME) ## builds a dynamic executable or package | ||
|
|
||
| $(NAME): *.go VERSION | ||
| @echo "+ $@" | ||
| mkdir -p dist | ||
| go build -tags "$(BUILDTAGS)" ${GO_LDFLAGS} -o dist/$(NAME) . | ||
|
|
||
| .PHONY: static | ||
| static: ## Builds a static executable | ||
| @echo "+ $@" | ||
| CGO_ENABLED=0 go build \ | ||
| -tags "$(BUILDTAGS) static_build" \ | ||
| ${GO_LDFLAGS_STATIC} -o $(NAME) . | ||
|
|
||
| .PHONY: fmt | ||
| fmt: ## Verifies all files have men `gofmt`ed | ||
| @echo "+ $@" | ||
| @gofmt -s -l . | grep -v '.pb.go:' | grep -v vendor | tee /dev/stderr | ||
|
|
||
| .PHONY: lint | ||
| lint: ## Verifies `golint` passes | ||
| @echo "+ $@" | ||
| @golint ./... | grep -v '.pb.go:' | grep -v '_bindata.go' | grep -v vendor | tee /dev/stderr | ||
|
|
||
| .PHONY: test | ||
| test: ## Runs the go tests | ||
| @echo "+ $@" | ||
| @go test -v -tags "$(BUILDTAGS) cgo" $(shell go list ./... | grep -v vendor) | ||
|
|
||
| .PHONY: vet | ||
| vet: ## Verifies `go vet` passes | ||
| @echo "+ $@" | ||
| @go vet $(shell go list ./... | grep -v vendor) | grep -v '.pb.go:' | grep -v '_bindata.go' | tee /dev/stderr | ||
|
|
||
| .PHONY: install | ||
| ## Installs the executable or package | ||
| install: install-bin create-declarations-dir install-man | ||
|
|
||
| .PHONY: install-bin | ||
| install-bin: | ||
| @echo "Installing binary" | ||
| @go install . | ||
|
|
||
| .PHONY: create-declarations-dir | ||
| create-declarations-dir: | ||
| @echo "Creating declarations dir at ~/.karn/declarations" | ||
| @mkdir -p ${INSTALLDECLARATIONS} | ||
| @cp -r ${DECLARATIONDIR} ${INSTALLDECLARATIONS} | ||
|
|
||
| .PHONY: install-man | ||
| install-man: | ||
| @echo "Installing man page" | ||
| @gzip -fk karn.1 | ||
| @sudo cp karn.1.gz /usr/share/man/man1/ | ||
|
|
||
| .PHONY: bindata | ||
| bindata: | ||
| @which go-bindata > /dev/null || go get github.com/jteeuwen/go-bindata/go-bindata/... | ||
| @go-bindata -pkg generate -o generate/declarations_bindata.go declarations/... | ||
|
|
||
| define buildpretty | ||
| mkdir -p $(BUILDDIR)/$(1)/$(2); | ||
| GOOS=$(1) GOARCH=$(2) CGO_ENABLED=0 go build \ | ||
| -o $(BUILDDIR)/$(1)/$(2)/$(NAME) \ | ||
| -a -tags "$(BUILDTAGS) static_build netgo" \ | ||
| -installsuffix netgo ${GO_LDFLAGS_STATIC} .; | ||
| md5sum $(BUILDDIR)/$(1)/$(2)/$(NAME) > $(BUILDDIR)/$(1)/$(2)/$(NAME).md5; | ||
| sha256sum $(BUILDDIR)/$(1)/$(2)/$(NAME) > $(BUILDDIR)/$(1)/$(2)/$(NAME).sha256; | ||
| endef | ||
|
|
||
| .PHONY: cross | ||
| cross: *.go VERSION ## Builds the cross-compiled binaries, creating a clean directory structure (eg. GOOS/GOARCH/binary) | ||
| @echo "+ $@" | ||
| $(foreach GOOSARCH,$(GOOSARCHES), $(call buildpretty,$(subst /,,$(dir $(GOOSARCH))),$(notdir $(GOOSARCH)))) | ||
|
|
||
| define buildrelease | ||
| GOOS=$(1) GOARCH=$(2) CGO_ENABLED=0 go build \ | ||
| -o $(BUILDDIR)/$(NAME)-$(1)-$(2) \ | ||
| -a -tags "$(BUILDTAGS) static_build netgo" \ | ||
| -installsuffix netgo ${GO_LDFLAGS_STATIC} .; | ||
| md5sum $(BUILDDIR)/$(NAME)-$(1)-$(2) > $(BUILDDIR)/$(NAME)-$(1)-$(2).md5; | ||
| sha256sum $(BUILDDIR)/$(NAME)-$(1)-$(2) > $(BUILDDIR)/$(NAME)-$(1)-$(2).sha256; | ||
| endef | ||
|
|
||
| .PHONY: release | ||
| release: *.go VERSION ## Builds the cross-compiled binaries, naming them in such a way for release (eg. binary-GOOS-GOARCH) | ||
| @echo "+ $@" | ||
| $(foreach GOOSARCH,$(GOOSARCHES), $(call buildrelease,$(subst /,,$(dir $(GOOSARCH))),$(notdir $(GOOSARCH)))) | ||
|
|
||
| .PHONY: tag | ||
| tag: ## Create a new git tag to prepare to build a release | ||
| git tag -sa $(VERSION) -m "$(VERSION)" | ||
| @echo "Run git push origin $(VERSION) to push your new tag to GitHub and trigger a travis build." | ||
|
|
||
| .PHONY: clean | ||
| clean: ## Cleanup any build binaries or packages | ||
| @echo "+ $@" | ||
| $(RM) $(NAME) | ||
| $(RM) -r $(BUILDDIR) | ||
|
|
||
| .PHONY: help | ||
| help: | ||
| @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' | ||
| @echo "just type 'make' to build the karn cli. test target coming soon" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,61 +1,192 @@ | ||
| # KARN | ||
| ---- | ||
|
|
||
| Karn is a system for high level entitlements for seccomp and apparmor. It can be used to generate OCI compliant profiles that you can pass to your container runtime. | ||
|
|
||
| ---- | ||
|
|
||
| ## Table of contents | ||
|
|
||
| * [Goal](#user-content-goal) | ||
| * [How it works](#how-it-works) | ||
| * [Additional resources](#additional-resources) | ||
| * [Contact developer](#contact-developer) | ||
|
|
||
| ### Goal | ||
|
|
||
| Create a simple permission scheme for easily securing applications. Developers can just specify what their application will need permission to do and this tool will output the corresponding seccomp and apparmor configurations. Alternatively developers of non-containerized applications could import karn and apply entitlements in code at runtime. This can be thought of as [iOS entitlements](https://developer.apple.com/library/content/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/AboutEntitlements.html) for everyone! | ||
|
|
||
| ### How it works | ||
|
|
||
| **Declarations** - You can think of these as rule definitions. You define a declaration as corresponding to particular system calls, capabilities, FileSystem rules, Networking, and other security related rules. Each file will correspond to just a single declaration. Declartions should follow the naming convention of "<name>_declaration.toml". Declarations are combined to generate seccomp and apparmor profiles. Here's a couple examples of what a declaration looks like: | ||
|
|
||
| _dns\_declaration.toml_ | ||
| ``` | ||
| [System-Calls] | ||
| Allow = [ | ||
| "sendto", | ||
| "recvfrom", | ||
| "socket", | ||
| "connect" | ||
| ] | ||
| ``` | ||
|
|
||
| _chown_declaration.toml_ | ||
| ``` | ||
| [System-Calls] | ||
| Allow = [ | ||
| "chown", | ||
| "chown32", | ||
| "fchown", | ||
| "fchown32", | ||
| "fchownat", | ||
| "lchown", | ||
| "lchown32" | ||
| ] | ||
| [Capabilities] | ||
| Allow = ["chown"] # CAP_CHOWN | ||
| # Karn | ||
|
|
||
| <p align="center"> | ||
| <b>Use Karn to enforce seccomp rules in your code. Select the entitlements that your application needs and not the ones it doesn't need!</b> | ||
| </p> | ||
|
|
||
| <p align="center"> | ||
| <img src="karn.jpg" alt="karn" width="800"/> | ||
| </p> | ||
|
|
||
| ## Table of Contents | ||
| * [How it Works](#how-it-works) | ||
| * [Entitlements](#entitlements) | ||
| * [Dependencies](#dependencies) | ||
| * [Quick Start](#quick-start) | ||
| * [Library](#library) | ||
| * [Containers](#containers) | ||
|
|
||
| ## How it works | ||
|
|
||
| <i>Seccomp</i> is a security facility of the Linux kernel. It allows you to create filters for system calls on a process by process basis. For example, you can create a seccomp filter that would allow all system calls except for [chmod](http://man7.org/linux/man-pages/man2/fchmod.2.html). You can then load that filter into a running process. If the `chmod` system call is then used the kernel would return an error to your process which can handle it however it's programmed to. | ||
|
|
||
| Despite the power that seccomp provides, it's very difficult to use in practice. You must have deep knowledge of all system calls, and even then the task is daunting. This is where Karn comes in. | ||
|
|
||
| <i>Karn</i> uses entitlements to abstract away the need to know all the system calls your application will need. Getting started is as simple as familiarizing yourself with the entitlements Karn offers. | ||
|
|
||
| Karn's entitlements aren't quite allow or deny lists. The installed seccomp filter has a default action of 'Allow'. Meaning any unspecified system call in the filter will be allowed. On top of that, any Karn entitlement that is not specified will be Denied. This is to avoid superfluous blocking of obscure/harmless system calls. | ||
|
|
||
| Karn can be used for generating profiles for containers, or can be used as a library in your non-containerized application. See the quickstart guide below for more. | ||
|
|
||
| ## Entitlements | ||
|
|
||
| See godoc [here](https://godoc.org/github.com/grantseltzer/karn/go/pkg/entitlements) | ||
|
|
||
| ## Dependencies | ||
|
|
||
| If you are using Karn as a library for enforcing seccomp you must have: | ||
|
|
||
| - libseccomp-dev [debian-like](https://launchpad.net/ubuntu/+source/libseccomp) / [centos-like](https://rpmfind.net/linux/rpm2html/search.php?query=libseccomp-devel) | ||
|
|
||
| If you are using Karn to generate OCI compliant seccomp profiles to pass to containers, there are no external dependencies. | ||
|
|
||
| ## Quick Start | ||
|
|
||
| * [Library](#library) | ||
| * [Containers](#containers) | ||
|
|
||
| #### Library | ||
| Let's say you're writing a simple HTTP webserver in go: | ||
|
|
||
| ``` | ||
| package main | ||
| import ( | ||
| "fmt" | ||
| "net/http" | ||
| ) | ||
| func main() { | ||
| http.HandleFunc("/", HelloServer) | ||
| http.ListenAndServe(":8080", nil) | ||
| } | ||
| func HelloServer(w http.ResponseWriter, r *http.Request) { | ||
| fmt.Fprintf(w, "I can modprobe if you exploit me, %s!", r.URL.Path[1:]) | ||
| } | ||
| ``` | ||
|
|
||
| This program just handles incoming HTTP requests on a network sockets. I didn't include anything exploitable here for simplicity but try to imagine the possibility of an application vulnerablity. | ||
|
|
||
| The only relevant sounding entitlement is `NetworkConnection`. Let's apply it: | ||
|
|
||
|
|
||
| ```go | ||
| package main | ||
|
|
||
| import ( | ||
| "fmt" | ||
| "net/http" | ||
| Karn "github.com/grantseltzer/Karn/go/pkg/entitlements" | ||
| ) | ||
|
|
||
| func main() { | ||
|
|
||
| neededEntitlements := []Karn.Entitlement{ | ||
| "NetworkConnection" | ||
| } | ||
|
|
||
| err := Karn.ApplyEntitlements(neededEntitlements) | ||
| if err != nil { | ||
| log.Fatal(err) | ||
| } | ||
|
|
||
| http.HandleFunc("/", HelloServer) | ||
| http.ListenAndServe(":8080", nil) | ||
| } | ||
|
|
||
| func HelloServer(w http.ResponseWriter, r *http.Request) { | ||
| fmt.Fprintf(w, "I can modprobe if you exploit me, %s!", r.URL.Path[1:]) | ||
| } | ||
| ``` | ||
|
|
||
| From here you wouldn't notice any difference in your applications runtime, except now it has a lot less system calls that it can use! | ||
|
|
||
| #### Containers | ||
|
|
||
| Let's use the same example as above. This time, we're running the application inside a container. In that case it's better to pass a seccomp profile to the container runtime instead of inside the application. This way the seccomp rules will be applied to every process inside the container. | ||
|
|
||
| We can build the karn CLI with a simple `make`. | ||
|
|
||
| From there, we're going to create the profile and then pass it with the container when we start it. | ||
|
|
||
| These declarations should be stored in `~/.karn/declarations`. To take these two declarations to form seccomp and apparmor profiles, one would simply enter `karn generate chown dns`. You can also pass a different declaration directory with the `-d`/`--declarations` flag. | ||
| ```bash | ||
| [*] ./bin/karn network_connection > seccomp_profile.json | ||
|
|
||
| ### Additional resources | ||
| [*] cat seccomp_profile | ||
| { | ||
| "defaultAction": "SCMP_ACT_ALLOW", | ||
| "architectures": [ | ||
| "SCMP_ARCH_X86", | ||
| "SCMP_ARCH_X86_64" | ||
| ], | ||
| "syscalls": [ | ||
| { | ||
| "names": [ | ||
| "ntp_adjtime", | ||
| "adjtimex", | ||
| "clock_adjtime", | ||
| "clock_settime", | ||
| "settimeofday", | ||
| "stime", | ||
| "pivot_root", | ||
| "kexec_file_load", | ||
| "kexec_load", | ||
| "ioperm", | ||
| "iopl", | ||
| "quotactl", | ||
| "execve", | ||
| "execveat", | ||
| "fork", | ||
| "vfork", | ||
| "swapon", | ||
| "swapoff", | ||
| "mount", | ||
| "umount", | ||
| "umount2", | ||
| "sysfs", | ||
| "_sysctl", | ||
| "personality", | ||
| "ustat", | ||
| "nfsservctl", | ||
| "vm86", | ||
| "uselib", | ||
| "vm86old", | ||
| "reboot", | ||
| "add_key", | ||
| "request_key", | ||
| "keyctl", | ||
| "unshare", | ||
| "setns", | ||
| "mknod", | ||
| "get_mempolicy", | ||
| "set_mempolicy", | ||
| "move_pages", | ||
| "mbind", | ||
| "acct", | ||
| "ptrace", | ||
| "lookup_dcookie", | ||
| "bpf", | ||
| "perf_event_open", | ||
| "process_vm_readv", | ||
| "process_vm_writev", | ||
| "create_module", | ||
| "delete_module", | ||
| "finit_module", | ||
| "get_kernel_syms", | ||
| "init_module", | ||
| "query_module", | ||
| "chown", | ||
| "fchown", | ||
| "fchownat", | ||
| "lchown" | ||
| ], | ||
| "action": "SCMP_ACT_ERRNO" | ||
| } | ||
| ] | ||
| } | ||
|
|
||
| - [system calls](http://man7.org/linux/man-pages/man2/syscalls.2.html) - the 'API' of the kernel | ||
| - [capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html) - a way of granting permissions | ||
| - [seccomp](http://man7.org/linux/man-pages/man2/seccomp.2.html) - a system call filtering facility | ||
| - [apparmor](http://wiki.apparmor.net/index.php/Main_Page) - a security facility for specifying various security rules such as capabilities | ||
| [*] docker build # (building your container with your application) | ||
|
|
||
| ### Notice | ||
| Please file bug reports and feature requests! Karn is very much in Alpha stages. | ||
| [*] docker run --rm -d --security-opt seccomp=./seccomp_profile.json <your_image> <you_app_command_line> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1 @@ | ||
| 0.0.1 | ||
| 2.0.0 |
Oops, something went wrong.