kntrl is an eBPF based runtime agent that monitors and prevents anomalous behaviour defined by you on your pipeline. kntrl achieves this by monitoring kernel calls, and denying access as soon as your defined behaviour is detected. Refer to this presentation to dive deeper into how we are achieving what kntrl does.

It can work as a single binary (kntrl) or with a docker runner (docker.io/kondukto/kntrl:0.1.2).

Installation

Linux

kntrl is available as downloadable binaries from the releases page. Download the pre-compiled binary from the releases page and copy to the desired location.

Container Images

We provide ready to use Docker container images. To pull the latest image:

docker pull kondukto/kntrl:latest

To pull a specific version:

docker pull kondukto/kntrl:0.1.4

Using kntrl

You can start using kntrl agent by simply running the following command, if you pass --daemonize flag the process will run in the background:

- name: start kntrl agent
  run: sudo ./kntrl start --mode=monitor --allowed-hosts=download.kondukto.io,${{ env.GITHUB_ACTIONS_URL }} --allowed-ips=10.0.2.3  --daemonize

to stop kntrl and print reports:

- name: stop kntrl agent
  run: sudo ./kntrl stop

OR with the docker:

- name: kntrl agent
  run: sudo docker start --privileged \
    --pid=host \
    --network=host \
    --cgroupns=host \
    --volume=/sys/kernel/debug:/sys/kernel/debug:ro \
    --volume /tmp:/tmp \
    --rm docker.io/kondukto/kntrl:0.1.2 run --mode=trace --allowed-hosts=kondukto.io,download.kondukto.io

This action will deploy kntrl into any GitHub Actions build.

Usage

The kntrl agent is self explanatory and it comes with a help command. Simply run --help flag after each command/subcommand.

 ./kntrl --help
Usage:
  kntrl [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  start       Start kntrl
  status      Print kntrl daemon status
  stop        Stop kntrl daemon

Flags:
  -h, --help      help for kntrl
  -v, --verbose   more logs
      --version   version for kntrl

Use "kntrl [command] --help" for more information about a command.
Runtime security tool to control and monitor egress/ingress traffic in CI/CD runners

The agent supports the following parameters:

| Name                 | Default          | Description                                                         |
| -------------------- | ---------------- | ------------------------------------------------------------------- | --- |
| `mode`               | monitor          | kntrl for detected behaviours (monitor or prevent/trace)            |
| `allowed-hosts`      |                  | allowed host list. (example.com, .github.com)                       |
| `allowed-ips`        |                  | allowed IP list. (192.168.0.100, 1.1.1.1)                           |
| `allow-local-ranges` | true             | allow access to local IP ranges                                     |
| `allow-github-meta`  | false            | allow access to GitHub meta IP ranges (https://api.github.com/meta) |
| `output-file`        | `/tmp/kntrl.out` | report file                                                         |     |

Running kntrl on monitoring mode

- name: kntrl agent
  run: sudo docker start --privileged \
  --pid=host \
  --network=host \
  --cgroupns=host \
  --volume=/sys/kernel/debug:/sys/kernel/debug:ro \
  --volume /tmp:/tmp \
  --rm docker.io/kondukto/kntrl:0.1.2 \
  --mode=monitor

Running kntrl on prevent mode

- name: kntrl agent
  run: sudo docker start --privileged \
  --pid=host \
  --network=host \
  --cgroupns=host \
  --volume=/sys/kernel/debug:/sys/kernel/debug:ro \
  --volume /tmp:/tmp \
  --rm docker.io/kondukto/kntrl:0.1.2 \
  --mode=trace --allowed-hosts=download.kondukto.io, .github.com

Open Policy Agent (OPA) Rules

kntrl supports an OPA-based policy engine to determine whether the event should be blocked or not. All the policy rules are stored under the bundle/kntrl/ directory.

An example rego rule:

package kntrl.network["is_local_ip_addr"]

import rego.v1

policy if {
        ipaddr := input.daddr
        local_ranges := ["192.168.0.0/16", "172.16.0.0/12", "10.0.0.0/8", "0.0.0.0/32"]
        net.cidr_contains(local_ranges[_], ipaddr)
        data.allow_local_ip_ranges == true
}

Reporting

Each event will be logged in the output file. The default report file location is /tmp/kntrl.out.

Here is an example report:

{
  "pid": 2806,
  "task_name": "curl",
  "proto": "tcp",
  "daddr": "140.82.114.22",
  "dport": 443,
  "domains": [
    "lb-140-82-114-22-iad.github.com."
  ],
  "policy": "pass"
}
{
  "pid": 2806,
  "task_name": "curl",
  "proto": "tcp",
  "daddr": "142.251.167.95",
  "dport": 443,
  "domains": [
    "ww-in-f95.1e100.net."
  ],
  "policy": "block"
}
{
  "pid": 2806,
  "task_name": "curl",
  "proto": "udp",
  "daddr": "127.0.0.1",
  "dport": 53,
  "domains": [
    "localhost"
  ],
  "policy": "pass"
}

or

Pid  | Comm    | Proto | Domain                          | Destination Addr   | Policy
------------------------------------------------------------------------------------
2806 | curl    | tcp   | lb-140-82-114-22-iad.github.com | 140.82.114.22:443  | pass
------------------------------------------------------------------------------------
2806 | curl    | tcp   | ww-in-f95.1e100.net             | 142.251.167.95:443 | block
------------------------------------------------------------------------------------
2806 | curl    | udp   | localhost                       | 127.0.0.1:53       | pass
------------------------------------------------------------------------------------

Contribution

Contributions to kntrl are welcome. Feel free to join our slack channel https://kntrl.slack.com

License

Except for the eBPF code, all components are distributed under the Apache License (version 2.0).

More about Kondukto

kntrl is an open source project maintained by Kondukto.