Several mechanics have been implemented to allow seamless integration with GitHub Actions.
GitHub Hosted Runners Support
The most popular environment for running GitHub Actions build is GitHub-hosted runners. As soon as a job is submitted, it is translated into a VM created by GitHub and run on GitHub's Azure-backed cloud.
In short, Cimon Agent is runner-aware, which means it is aware of the runner environment and adapts itself accordingly. There are several ways in which the functionality reflects this:
- Hosted Runner Support - Cimon will be compatible with any Ubuntu-based hosted runner.
- Allowed Hosts - Github-related hosts will be added automatically, including
- Ignored IPs - Ignoring internal IPs communication, such as the Azure metadata IP address
127.0.0.1, and more.
- Performance - To improve the performance, it will track the descendant processes of the pipeline runner process,
Runner.Workerin the case of GitHub Actions (it will also track docker-related processes due to their relevance)
- GitHub Reporters - It will output the report according to the runner identified. In the GitHub Actions case, that would be a job summary report.
GitHub Actions also allows running jobs inside containers. The setup adds several constraints and hasn't been fully tested yet. When using Cimon on GitHub-hosted machines, we recommend running it natively instead of in a container.
Cimon GitHub Action
As part of Cimon, we provide a custom action for deploying agents seamlessly within any GitHub Actions build. The repository containing the action can be found at https://github.com/cycodelabs/cimon-action. The action also could be found on GitHub's official marketplace at https://github.com/marketplace/actions/cimon-by-cycode.
The action is based on the NodeJS engine and contains simple
post scripts to start and gracefully shut down the agent's container. Cimon is run as a privileged container in detached mode and joins the runners' process and network namespaces to see all the processes and network connections on the host.
The action supports the following parameters:
|Cimon client ID for authentication|
|Cimon secret for authentication|
|Cimon endpoint for authentication|
|Enable prevention mode|
|A comma or white space separated list of allowed IP addresses|
|A comma or white space separated list of allowed domain names. The left-most label can be the wildcard character (|
|A comma or white space separated list of ignored IP networks in CIDR notation, e.g. 10.0.0.0/8, 172.16.0.0/12. This setting is mandatory if your workflow runs containers attached to a custom network with configured sub-range. In other words, inter-container networking is usually ignored by Cimon. Cimon implicitly ignores 10.0.0.0/8 and 172.16.0.0/12 networks.|
|GitHub token (used to overcome GitHub rate limiting)|
|Report results through job summary output|
|Enable to report the process tree|
|Slack webhook endpoint to report security events|
|Enable processing filesystem events and display them in the process tree report|
|Log level (Used for debugging)|
|Set of key=value pairs that describe Cimon features|
|Fail the CI if Cimon encountered an error|
We welcome contributions to the GitHub Action project.
After changes were made to the
src folder, changes should be reflected in the
dist folder by the following steps:
- Install or update package dependencies:
npm run all
The build script will update actions' entry points code in the dist directory, which should be added to the Git repository.
Job Summary Report
What is Job Summary
Job Summary feature provides a more detailed and customizable summary of the results of each job in a workflow, including the ability to include custom metadata, rich text formatting, and images.
Cimon generates a summary report for every job defined in a workflow. The layout and contents of the report depend on the runtime mode, i.e., detect or prevent.
Here is an example of a standard security report in GitHub:
- Detect Mode
- Prevent Mode
The headline indicates whether any risk was detected at runtime. If yes, the subsequent sections provide enough information to understand which program was blocked due to a forbidden network connection, including a process identifier, destination address, port, and protocol.
The Policy Suggestion section shows the recommended Cimon GitHub action configuration to apply in prevent mode. In other words, based on that information, Cimon builds a profile of network events in detect mode and suggests allowed IP addresses and hosts as input configurations in prevent mode.
A typical section is a list of Network Events, i.e., outbound TCP and UDP connections, which includes the integer process identifier (PID) that initiated the connection, process name, destination IP address and port, and resolved host. The last column indicates forbidden connections that are blocked in prevention mode.
Another typical section shows Resolved Domains, i.e., DNS mapping between hosts and corresponding IP addresses.
If reporting process tree is enabled, a summary report includes the Process Tree captured during workflow execution by instrumenting GitHub runner's application (
Runner.Worker) and container runtime (
dockerd) and their descendants. Effectively, it shows all processes and programs with command-line arguments run during workflow execution.
Runner.Worker(1528) [ /home/runner/runners/2.301.1/bin/Runner.Worker spawnclient 112 115 ]
node(4299) [ /home/runner/runners/2.301.1/externals/node16/bin/node /home/runner/work/_actions/actions/checkout/93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8/dist/index.js ]
git(4310) [ /usr/bin/git version ]
git(4311) [ /usr/bin/git config --global --add safe.directory /home/runner/work/cimon/cimon/Hello-World ]
git(4312) [ /usr/bin/git init /home/runner/work/cimon/cimon/Hello-World ]
containerd(672) [ /usr/bin/containerd ]
containerd-shim(4419) [ /usr/bin/containerd-shim-runc-v2 -namespace moby -address /run/containerd/containerd.sock -publish-binary /usr/bin/containerd -id 8bd93947b2ac106fae58e095807422f0acc6bd170f76520e645328a170f502c4 start ]
containerd-shim(4427) [ /usr/bin/containerd-shim-runc-v2 -namespace moby -id 8bd93947b2ac106fae58e095807422f0acc6bd170f76520e645328a170f502c4 -address /run/containerd/containerd.sock ]
runc(4437) [ /usr/bin/runc --root /var/run/docker/runtime-runc/moby --log /run/containerd/io.containerd.runtime.v2.task/moby/8bd93947b2ac106fae58e095807422f0acc6bd170f76520e645328a170f502c4/log.json --log-format json create --bundle /run/containerd/io.containerd.runtime.v2.tas ]
exe(4446) [ runc init ]
6(4446) [ runc init ]
wget(4448) [ /bin/wget --timeout=1 https://yahoo.com ]