# Installing kube-forensics > Creates checkpoint snapshots of the state of running pods for later off-line analysis. kube-forensics allows a cluster administrator to dump the current state of a running pod and all its containers so that security professionals can perform off-line forensic analysis. In the event of a security breach, members of the Security Team need to examine the state of the Pod and perform a detailed forensics analysis to determine the mode of attack. However, the business would like to terminate the Pod and get back to normal processing as quickly as possible. kube-forensics was developed to allow a cluster administrator to dump the state of a running Pod for offline analysis. The forensics-controller-manager manages a PodCheckpoint custom resource definition (CRD). The PodCheckpoint resource runs a Kubernetes Job on the same node as the target pod and performs the equivalent of the following operations on the indicated pod/containers by mounting the Docker socket: ``` bash docker inspect docker diff docker export ``` In addition, it collects some meta-data about the target pod by running the equivalent of the following: ```bash kubectl describe pod kubectl get pod ``` The output is uploaded to the destination S3 bucket. ## Installation You must have cluster administrator access to deploy kube-forensics to a running cluster. 1. Ensure your `KUBECONFIG` and current context correctly points to the desired cluster. 1. Checkout kube-forensics repository 1. Change directory into the root of the repository 1. Run `make deploy` Begin by cloning the Git repository for kube-forensics ```bash git clone https://github.com/keikoproj/kube-forensics.git ``` Change directories to `/kube-forensics` and build the solution. For example: ```bash cd kube-forensics make deploy ``` ``` /Users/tekenstam/go/bin/controller-gen "crd:trivialVersions=true" rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases kubectl apply -f config/crd/bases customresourcedefinition.apiextensions.k8s.io/podcheckpoints.forensics.keikoproj.io configured kustomize build config/default | kubectl apply -f - namespace/forensics-system unchanged customresourcedefinition.apiextensions.k8s.io/podcheckpoints.forensics.keikoproj.io configured role.rbac.authorization.k8s.io/forensics-leader-election-role unchanged clusterrole.rbac.authorization.k8s.io/forensics-manager-role configured clusterrole.rbac.authorization.k8s.io/forensics-proxy-role unchanged rolebinding.rbac.authorization.k8s.io/forensics-leader-election-rolebinding unchanged clusterrolebinding.rbac.authorization.k8s.io/forensics-manager-rolebinding unchanged clusterrolebinding.rbac.authorization.k8s.io/forensics-proxy-rolebinding unchanged service/forensics-controller-manager-metrics-service unchanged deployment.apps/forensics-controller-manager unchanged ``` ## Usage example Once the kube-forensics controller is installed, a `PodCheckpoint` spec can be submitted for processing. <!--- ## Update the ServiceAccount to use IRSA Ordinarily, kube-forensics requires worker nodes to have an IAM role that allows the PutObject API call to an S3 bucket. For this exercise, we are going to update the job's ServiceAccount to use IAM Roles for Service Accounts (IRSA) instead. 1. Create an S3 bucket. Copy the Arn of the bucket. 2. Download and run the `create-role` binary from the workshop repository. Copy the Arn from the output. ```bash create-role -bucketArn <BUCKET_ARN> -clusterName <CLUSTER_NAME> ``` 3. Annotate the forensics-worker ServiceAccount role with the role Arn. ```bash kubectl annotate sa forensics-worker -n forensics-system eks.amazonaws.com/role-arn=<ROLE_ARN> ``` Apply this change before creating the custom resource for the job. ### Sample spec Save the following `yaml` file to `example.yaml` and modify the `destination`, `pod` and `namespace` to valid values for your cluster. ``` yaml apiVersion: forensics.keikoproj.io/v1alpha1 kind: PodCheckpoint metadata: name: podcheckpoint-sample namespace: forensics-system spec: destination: s3://my-bucket-123456789000-us-west-2 subpath: forensics pod: bad-pod-1234567890-dead1 namespace: default ``` --> ### Submit & Verify ```bash kubectl apply -f ./config/samples/forensics_v1alpha1_podcheckpoint.yaml ``` podcheckpoint.forensics.keikoproj.io/podcheckpoint-sample created ```bash kubectl get -n forensics-system PodCheckpoint ``` ``` NAME AGE podcheckpoint-sample 33s ``` Check the state of the PodCheckpoint. ```bash kubectl describe PodCheckpoint -n forensics-system podcheckpoint-sample ``` ``` Name: podcheckpoint-sample Namespace: forensics-system Labels: <none> Annotations: kubectl.kubernetes.io/last-applied-configuration: {"apiVersion":"forensics.keikoproj.io/v1alpha1","kind":"PodCheckpoint","metadata":{"annotations":{},"name":"podcheckpoint-sample","namespac... API Version: forensics.keikoproj.io/v1alpha1 Kind: PodCheckpoint Metadata: Creation Timestamp: 2019-08-14T23:19:13Z Generation: 2 Resource Version: 595318 Self Link: /apis/forensics.keikoproj.io/v1alpha1/namespaces/forensics-system/podcheckpoints/podcheckpoint-sample UID: edbe3bd6-bee9-11e9-a5c6-0afa5b77e74c Spec: Destination: s3://my-bucket-123456789000-us-west-2 Namespace: default Pod: bad-pod-1234567890-dead1 Subpath: forensics Status: Completion Time: 2019-08-14T23:19:13Z Conditions: Last Probe Time: 2019-08-14T23:19:13Z Last Transition Time: 2019-08-14T23:19:13Z Message: The specified Pod 'bad-pod-1234567890-dead1' was not found in the 'default' namespace. Reason: NotFound Status: True Type: Failed Start Time: 2019-08-14T23:19:13Z Events: <none> ``` In the above output you can see the PodCheckpoint failed due to the Pod name not being found in the system. ## Next Steps When you're finished experimenting with kube-forensics, click this [link](./README.md) to return to the page on isolating the attack.