Testing Guide

  • Test in manual 1. Run 'kubectl proxy' in background

    $ kubectl proxy &
    1. Run KubeArmor

      $ cd KubeArmor/KubeArmor
      ~/KubeArmor/KubeArmor$ make clean && make
      ~/KubeArmor/KubeArmor$ make run

      If you want to change the number of the gRPC port or the location of a log file, run KubeArmor like the below.

      ~/KubeArmor/KubeArmor$ sudo -E ./kubearmor -gRPC=[gRPC port number]
      -logPath=[log file path]
      -enableHostPolicy
    2. Apply security policies for testing

      $ kubectl apply -f [policy file]

      You can refer to the security policies defined for example microservices in examples.

    3. Trigger policy violations to generate logs

      $ kubectl -n [namespace name] exec -it [pod name] -- bash -c [command]
    4. Check KubeArmor's alerts and logs

      • Log file

        $ tail (-f) /tmp/kubearmor.log

        If you changed the location of a log file, check your file instead of the default file path.

        $ tail (-f) [your log file path]
      • Log client

        Compile a log client.

        $ cd KubeArmor/LogClient
        ~/KubeArmor/LogClient$ make

        Run the log client.

        ~/KubeArmor/LogClient$ ./kubearmor-log-client (options...)

        Log client options:

        -gRPC=[ipaddr:port] gRPC server information (default: localhost:32767)
        -msgPath={path|stdout|none} Output location for KubeArmor's messages (default: none)
        -logPath={path|stdout|none} Output location for KubeArmor's alerts and logs (default: stdout)
        -logFilter={policy|system|all} Filter for what kinds of alerts and logs to receive (default: policy)
        -json Flag to print messages, alerts, and logs in a JSON format

        Note that you will see the messages, alerts, and logs generated right after the log client runs, which means that the log client should be ran before any policy violations happen.

  • Test using the auto-testing framework

    1. Testcases

      To use the auto-testing framework, you need to define two things: microservices and scenarios for each microservice.

      • Microservices

        Create a directory for a microservice in microservices.

        $ cd KubeArmor/tests/microservices
        ~/KubeArmor/tests/microservices$ mkdir [microservice name]

        Then, create YAML files for the microservice.

        $ cd KubeArmor/tests/microservices/[microservice name]
        ~/KubeArmor/tests/microservices/[microservice name]$ ...

        As an example, we created 'multiubuntu' in microservices, and defined 'multiubuntu-deployment.yaml' in multiubuntu.

      • Test scenarios

        Create a directory whose name is like '[microservice name]_[test scenario name]' in scenarios.

        $ cd KubeArmor/tests/scenarios
        ~/KubeArmor/tests/scenarios$ mkdir [microservice name]_[test scenario name]

        Then, define a YAML file for a test policy in the directory.

        ~/KubeArmor/tests/scenarios$ cd [microservice name]_[test scenario name]
        .../[microservice name]_[test scenario name]$ vi [policy name].yaml

        As a next step, create cmd files whose names are like 'cmd#'.

        .../[microservice name]_[test scenario name]$ vi cmd1 / cmd2 / ...

        Here is a template for a cmd file.

        source: [pod name]
        cmd: [command to trigger a policy violation]
        result: [expected result], { passed | failed }
        ---
        operation: [operation], { Process | File | Network }
        condition: [matching string]
        action: [action in a policy]

        This is an example of a scenario.

        source: ubuntu-1-deployment
        cmd: sleep 1
        result: failed
        ---
        operation: Process
        condition: sleep
        action: Block

        You can refer to our scenarios in scenarios.

    2. Test KubeArmor in a local development environment

      • In the case that KubeArmor is not running

        Compile KubeArmor.

        $ cd KubeArmor/KubeArmor
        ~/KubeArmor/KubeArmor$ make clean && make

        Make sure that 'kubectl proxy' is running.

        $ kubectl proxy &

        Run the auto-testing framework (the framework will automatically run KubeArmor).

        $ cd KubeArmor/tests
        ~/KubeArmor/tests$ ./test-scenarios-local.sh

        Check the test report

        ~/KubeArmor/tests$ cat /tmp/kubearmor.test
      • In the case that KubeArmor is running

        Run the auto-testing framework. Please make sure that KubeArmor is in a running state.

        $ cd KubeArmor/tests
        ~/KubeArmor/tests$ ./test-scenarios-in-runtime.sh

        Check the test report

        ~/KubeArmor/tests$ cat /tmp/kubearmor.test
    3. Test the containerized KubeArmor image using MicroK8s

      Run the auto-testing framework.

      $ cd KubeArmor/tests
      ~/KubeArmor/tests$ ./test-scenarios-with-microk8s.sh

      Check the test report

      ~/KubeArmor/tests$ cat /tmp/kubearmor.test
    4. Test the containerized KubeArmor image on running Kubernetes

      Run the auto-testing framework. Please make sure that KubeArmor is in a running state.

      $ cd KubeArmor/tests
      ~/KubeArmor/tests$ ./test-scenarios-in-runtime.sh

      Check the test report

      ~/KubeArmor/tests$ cat /tmp/kubearmor.test