Skip to content

chore: autogenerate audit log documentation #5862

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Jan 26, 2023
Merged

chore: autogenerate audit log documentation #5862

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
51c7aee
added script for table creation
Kira-Pilot Jan 25, 2023
0facafe
added tags to audit-logs.md
Kira-Pilot Jan 25, 2023
963552a
removed log
Kira-Pilot Jan 25, 2023
e1a9fbb
removed empty block line
Kira-Pilot Jan 25, 2023
f2b4595
PR feedback
Kira-Pilot Jan 26, 2023
bcd67a2
modify check_unstaged
Kira-Pilot Jan 26, 2023
dfe78c3
third times the charm maybe
Kira-Pilot Jan 26, 2023
d9a1ab0
spelling
Kira-Pilot Jan 26, 2023
1906daa
relative path
Kira-Pilot Jan 26, 2023
a6891dc
excluding from the right script this time
Kira-Pilot Jan 26, 2023
be44d6c
sorted resources to ensure table order
Kira-Pilot Jan 26, 2023
f96cbe3
running make cmd
Kira-Pilot Jan 26, 2023
0e1903d
running make again
Kira-Pilot Jan 26, 2023
f3ec8f5
ensuring order on subtable
Kira-Pilot Jan 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
added tags to audit-logs.md
  • Loading branch information
@Kira-Pilot
Kira-Pilot committed Jan 25, 2023
commit 0facafef8f0ea6e3ba065a79993c622fb378f108
2 changes: 2 additions & 0 deletions .vscode/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,7 @@
"tailnet",
"tailnettest",
"Tailscale",
"tbody",
"TCGETS",
"tcpip",
"TCSETS",
Expand All @@ -128,6 +129,7 @@
"tfjson",
"tfplan",
"tfstate",
"thead",
"tios",
"tmpdir",
"tparallel",
Expand Down
7 changes: 7 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -418,6 +418,7 @@ gen: \
provisionerd/proto/provisionerd.pb.go \
site/src/api/typesGenerated.ts \
docs/admin/prometheus.md \
docs/admin/audit-logs.md \
coderd/apidoc/swagger.json \
.prettierignore.include \
.prettierignore \
Expand All @@ -436,6 +437,7 @@ gen/mark-fresh:
provisionerd/proto/provisionerd.pb.go \
site/src/api/typesGenerated.ts \
docs/admin/prometheus.md \
docs/admin/audit-logs.md \
coderd/apidoc/swagger.json \
.prettierignore.include \
.prettierignore \
Expand Down Expand Up @@ -490,6 +492,11 @@ docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/me
cd site
yarn run format:write:only ../docs/admin/prometheus.md

docs/admin/audit-logs.md: scripts/auditdocgen/main.go enterprise/audit/table.go
go run scripts/auditdocgen/main.go
cd site
yarn run format:write:only ../docs/admin/audit-logs.md

coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen $(FIND_EXCLUSIONS) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) .swaggo docs/manifest.json
./scripts/apidocgen/generate.sh
yarn run --cwd=site format:write:only ../docs/api ../docs/manifest.json ../coderd/apidoc/swagger.json
Expand Down
26 changes: 17 additions & 9 deletions docs/admin/audit-logs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,23 @@ their deployment.

## Tracked Events

We track **create, update and delete** events for the following resources:

- GitSSHKey
- Template
- TemplateVersion
- Workspace
- WorkspaceBuild
- User
- Group
We track the following resources:

<!-- Code generated by 'make docs/admin/audit-logs.md'. DO NOT EDIT -->

| <b>Resource<b> | |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AuditableGroup | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>avatar_url</td><td>true</td></tr><tr><td>quota_allowance</td><td>true</td></tr><tr><td>members</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>organization_id</td><td>false</td></tr></tbody></table> |
| Organization | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>id</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>description</td><td>true</td></tr><tr><td>created_at</td><td>false</td></tr><tr><td>updated_at</td><td>false</td></tr></tbody></table> |
| OrganizationMember | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>updated_at</td><td>false</td></tr><tr><td>roles</td><td>true</td></tr><tr><td>user_id</td><td>true</td></tr><tr><td>organization_id</td><td>true</td></tr><tr><td>created_at</td><td>false</td></tr></tbody></table> |
| User | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>deleted</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>username</td><td>true</td></tr><tr><td>rbac_roles</td><td>true</td></tr><tr><td>login_type</td><td>false</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>hashed_password</td><td>true</td></tr><tr><td>status</td><td>true</td></tr><tr><td>last_seen_at</td><td>false</td></tr><tr><td>email</td><td>true</td></tr><tr><td>created_at</td><td>false</td></tr><tr><td>avatar_url</td><td>false</td></tr></tbody></table> |
| Workspace | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>id</td><td>true</td></tr><tr><td>template_id</td><td>true</td></tr><tr><td>deleted</td><td>false</td></tr><tr><td>name</td><td>true</td></tr><tr><td>organization_id</td><td>false</td></tr><tr><td>owner_id</td><td>true</td></tr><tr><td>autostart_schedule</td><td>true</td></tr><tr><td>ttl</td><td>true</td></tr><tr><td>last_used_at</td><td>false</td></tr><tr><td>created_at</td><td>false</td></tr><tr><td>updated_at</td><td>false</td></tr></tbody></table> |
| WorkspaceBuild | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created_at</td><td>false</td></tr><tr><td>job_id</td><td>false</td></tr><tr><td>id</td><td>false</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>template_version_id</td><td>true</td></tr><tr><td>initiator_id</td><td>false</td></tr><tr><td>deadline</td><td>false</td></tr><tr><td>daily_cost</td><td>false</td></tr><tr><td>build_number</td><td>false</td></tr><tr><td>provisioner_state</td><td>false</td></tr><tr><td>reason</td><td>false</td></tr><tr><td>workspace_id</td><td>false</td></tr><tr><td>transition</td><td>false</td></tr></tbody></table> |
| GitSSHKey | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created_at</td><td>false</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>private_key</td><td>true</td></tr><tr><td>public_key</td><td>true</td></tr><tr><td>user_id</td><td>true</td></tr></tbody></table> |
| Template | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>updated_at</td><td>false</td></tr><tr><td>provisioner</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>default_ttl</td><td>true</td></tr><tr><td>organization_id</td><td>false</td></tr><tr><td>icon</td><td>true</td></tr><tr><td>min_autostart_interval</td><td>true</td></tr><tr><td>deleted</td><td>false</td></tr><tr><td>display_name</td><td>true</td></tr><tr><td>group_acl</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>created_at</td><td>false</td></tr><tr><td>created_by</td><td>true</td></tr><tr><td>user_acl</td><td>true</td></tr><tr><td>is_private</td><td>true</td></tr><tr><td>active_version_id</td><td>true</td></tr><tr><td>allow_user_cancel_workspace_jobs</td><td>true</td></tr><tr><td>description</td><td>true</td></tr></tbody></table> |
| TemplateVersion | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>id</td><td>true</td></tr><tr><td>template_id</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>created_at</td><td>false</td></tr><tr><td>updated_at</td><td>false</td></tr><tr><td>readme</td><td>true</td></tr><tr><td>job_id</td><td>false</td></tr><tr><td>created_by</td><td>true</td></tr><tr><td>organization_id</td><td>false</td></tr></tbody></table> |

<!-- End generated by 'make docs/admin/audit-logs.md'. -->

## Filtering logs

Expand Down
62 changes: 56 additions & 6 deletions scripts/auditdocgen/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,33 @@ package main

import (
"bytes"
"flag"
"fmt"
"log"
"os"
"strconv"
"strings"

"golang.org/x/xerrors"

"github.com/coder/coder/enterprise/audit"
)

var (
auditDocFile string
dryRun bool

generatorPrefix = []byte("<!-- Code generated by 'make docs/admin/audit-logs.md'. DO NOT EDIT -->")
generatorSuffix = []byte("<!-- End generated by 'make docs/admin/audit-logs.md'. -->")
)

type AuditableResourcesMap map[string]map[string]bool

func main() {
flag.StringVar(&auditDocFile, "audit-doc-file", "docs/admin/audit-logs.md", "Path to audit log doc file")
flag.BoolVar(&dryRun, "dry-run", false, "Dry run")
flag.Parse()

auditableResourcesMap, err := readAuditableResources()
if err != nil {
log.Fatal("can't read auditableResources: ", err)
Expand All @@ -26,14 +44,19 @@ func main() {
log.Fatal("can't update audit doc: ", err)
}

if dryRun {
log.Println(string(doc))
return
}

err = writeAuditDoc(doc)
if err != nil {
log.Fatal("can't write updated audit doc: ", err)
}
}

type AuditableResourcesMap map[string]map[string]bool

// Transforms audit.AuditableResources to AuditableResourcesMap,
// which uses friendlier language.
func readAuditableResources() (AuditableResourcesMap, error) {
auditableResourcesMap := make(AuditableResourcesMap)

Expand All @@ -49,16 +72,35 @@ func readAuditableResources() (AuditableResourcesMap, error) {
return auditableResourcesMap, nil
}

// Reads the content of docs/admin/audit-logs.md
func readAuditDoc() ([]byte, error) {
var doc []byte
doc, err := os.ReadFile(auditDocFile)
if err != nil {
return nil, err
}
fmt.Println("document returned", doc)

return doc, nil
}

// Writes a markdown table of audit log resources to a buffer
func updateAuditDoc(doc []byte, auditableResourcesMap AuditableResourcesMap) ([]byte, error) {
var updatedDoc []byte
i := bytes.Index(doc, generatorPrefix)
if i < 0 {
return nil, xerrors.New("generator prefix tag not found")
}
tableStartIndex := i + len(generatorPrefix) + 1

j := bytes.Index(doc[tableStartIndex:], generatorSuffix)
if j < 0 {
return nil, xerrors.New("generator suffix tag not found")
}
tableEndIndex := tableStartIndex + j

var buffer bytes.Buffer
buffer.Write(doc[:tableStartIndex])
buffer.WriteByte('\n')

buffer.WriteString("|<b>Resource<b>||\n")
buffer.WriteString("|--|-----------------|\n")

Expand All @@ -73,10 +115,18 @@ func updateAuditDoc(doc []byte, auditableResourcesMap AuditableResourcesMap) ([]
buffer.WriteString("</tbody></table>\n")
}

fmt.Println("updated table", buffer.String())
return updatedDoc, nil
buffer.WriteString("\n")
buffer.Write(doc[tableEndIndex:])
return buffer.Bytes(), nil
}

// Updates docs/admin/audit-logs.md with new table content
func writeAuditDoc(doc []byte) error {
// G306: Expect WriteFile permissions to be 0600 or less
/* #nosec G306 */
err := os.WriteFile(auditDocFile, doc, 0644)
if err != nil {
return err
}
return nil
}