Update README with demo log

liggitt · Sep 11, 2017 · ed857a7 · ed857a7
1 parent 501d132
commit ed857a7
Showing 1 changed file with 65 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -11,45 +11,87 @@ audit2rbac is in the nascent stages of development, and will change internal and
 
 ## User Instructions
 
-1. Obtain a Kubernetes audit log containing all the API requests you expect your user to perform
-    * The log must be in JSON format (requires running an API server with `--feature-gates=AdvancedAudit=true` and a `--audit-policy-file` defined... see [documentation](https://kubernetes.io/docs/tasks/debug-application-cluster/audit/#advanced-audit) for more details)
-    * `v1alpha1` or `v1beta1` audit events are supported
-    * The `Metadata` log level works best to minimize log size
+1. Obtain a Kubernetes audit log containing all the API requests you expect your user to perform:
+    * The log must be in JSON format. This requires running an API server with `--feature-gates=AdvancedAudit=true` and an `--audit-policy-file` defined. See [documentation](https://kubernetes.io/docs/tasks/debug-application-cluster/audit/#advanced-audit) for more details.
+    * `v1alpha1` or `v1beta1` audit events are supported.
+    * The `Metadata` log level works best to minimize log size.
     * To exercise all API calls, it is sometimes necessary to grant broad access to a user or application to avoid short-circuiting code paths on failed API requests. This should be done cautiously, ideally in a development environment.
-2. Identify a specific user you want to generate roles for. This can be a normal user with a username like `bob` or a service account with a username like `system:serviceaccount:my-namespace:my-service-account`.
-3. Run `audit2rbac`, capturing the output
+    * A ([sample log](testdata/demo.log)) containing requests from `alice`, `bob`, and the service account `ns1:sa1` is available.
+2. Identify a specific user you want to scan for audit events for and generate roles and role bindings for:
+    * Specify a normal user with `--user <username>`
+    * Specify a service account with `--serviceaccount <namespace>:<name>`
+3. Run `audit2rbac`, capturing the output:
     ```sh
-    audit2rbac --filename audit.log --user system:serviceaccount:my-namespace:my-user > roles.yaml
-
-    Loading events...............................................
-    Evaluating API calls...
-    Generating roles...
-    Complete!
+    curl -s -O -L https://github.com/liggitt/audit2rbac/raw/master/testdata/demo.log
+    audit2rbac --filename demo.log --user alice             > alice-roles.yaml
+    audit2rbac --filename demo.log --user bob               > bob-roles.yaml
+    audit2rbac --filename demo.log --serviceaccount ns1:sa1 > sa1-roles.yaml
     ```
 4. Inspect the output to verify the generated roles/bindings:
     ```sh
-    more roles.yaml 
+    more alice-roles.yaml
+    ```
 
+    ```yaml
     apiVersion: rbac.authorization.k8s.io/v1
-    kind: ClusterRole
+    kind: Role
     metadata:
       creationTimestamp: null
       labels:
         audit2rbac.liggitt.net/generated: "true"
-        audit2rbac.liggitt.net/user: my-user
-      name: audit2rbac:my-user
+        audit2rbac.liggitt.net/user: alice
+      name: audit2rbac:alice
+      namespace: ns1
     rules:
     - apiGroups:
-    ...
+      - ""
+      resources:
+      - configmaps
+      verbs:
+      - get
+      - list
+      - watch
+    - apiGroups:
+      - ""
+      resources:
+      - pods
+      verbs:
+      - get
+      - list
+      - watch
+    - apiGroups:
+      - ""
+      resources:
+      - secrets
+      verbs:
+      - get
+      - list
+      - watch
+    ---
+    apiVersion: rbac.authorization.k8s.io/v1
+    kind: RoleBinding
+    metadata:
+      creationTimestamp: null
+      labels:
+        audit2rbac.liggitt.net/generated: "true"
+        audit2rbac.liggitt.net/user: alice
+      name: audit2rbac:alice
+      namespace: ns1
+    roleRef:
+      apiGroup: rbac.authorization.k8s.io
+      kind: Role
+      name: audit2rbac:alice
+    subjects:
+    - apiGroup: rbac.authorization.k8s.io
+      kind: User
+      name: alice
     ```
 5. Load the generated roles/bindings:
     ```sh
     kubectl create -f roles.yaml
 
-    clusterrole "audit2rbac:my-user" created
-    clusterrolebinding "audit2rbac:my-user" created
-    role "audit2rbac:my-user" created
-    rolebinding "audit2rbac:my-user" created
+    role "audit2rbac:alice" created
+    rolebinding "audit2rbac:alice" created
     ```
 
 ## Developer Instructions
@@ -58,11 +100,11 @@ Requirements:
 * Go 1.8+
 * Glide 0.12.3+
 
-To download, install dependencies, and build:
+To build and install from source:
 ```sh
 go get -d github.com/liggitt/audit2rbac
 cd $GOPATH/src/github.com/liggitt/audit2rbac
 git fetch --tags
 make install-deps
-make
+make install
 ```