Files
coder/scripts/auditdocgen/main.go
T
Nick Vigilante fcbf45c571 docs: render audit log resources as one table per resource (#29797)
## Summary

The audit logs page now lists each tracked resource in its own section
with a simple two-column table, replacing the nested HTML tables that
rendered poorly and overflowed on phones.

## Before and after

Before, the generated block was a single Markdown table with a malformed
`|<b>Resource</b>||` header.
Each row held the resource name and its actions in one cell, then split
a raw HTML `<table>` of fields across the remaining cells.
The result rendered unevenly across renderers, was far wider than the
page on mobile, and was hard to navigate with a screen reader.

After, each resource gets an `###` heading under **Tracked Events**,
which also gives it a linkable anchor.
Below the heading, an `Actions:` line lists the audited actions as
inline code, followed by a two-column Field and Tracked table with `Yes`
or `No` values.
Every table uses the same fixed column widths (Field 75%, Tracked 25%),
so the Tracked column lines up across all resources.
Two narrow columns fit at phone width without horizontal scrolling.
Resources with no mapped actions skip the `Actions:` line instead of
rendering an empty one.
Resource ordering is unchanged.

## Changes

- `scripts/auditdocgen/main.go` writes one section per resource.
Each fields table is a small HTML table with `width` attributes, because
Markdown tables size columns to their content and cannot align across
tables.
GitHub and the docs site sanitizer both keep `width` but strip inline
`style` and `<colgroup>`.
- The generator no longer panics when its start marker is the last thing
in the file.
- New `scripts/auditdocgen/main_test.go` covers section output, marker
handling, and idempotent regeneration.
- `docs/admin/security/audit-logs.md` is regenerated, and the intro
sentence above the block now explains the actions line and the Tracked
column.

## How it was regenerated

`make docs/admin/security/audit-logs.md`, which builds the generator and
runs `markdownlint-cli2 --fix` and `markdown-table-formatter` over the
output.
Running it a second time produces no diff.

## Testing

- `go test ./scripts/auditdocgen/...` passes.
- `pnpm exec markdownlint-cli2 docs/admin/security/audit-logs.md`
reports 0 errors.

Linear: https://linear.app/codercom/issue/DOCS-894

---
🤖 Built with AI assistance.
2026-10-02 15:05:10 -04:00

171 lines
4.9 KiB
Go

package main
import (
"bytes"
"flag"
"html"
"log"
"os"
"strings"
"golang.org/x/xerrors"
"github.com/coder/coder/v2/coderd/util/maps"
"github.com/coder/coder/v2/codersdk"
"github.com/coder/coder/v2/enterprise/audit"
"github.com/coder/coder/v2/scripts/atomicwrite"
)
var (
auditDocFile string
dryRun bool
generatorPrefix = []byte("<!-- Code generated by 'make docs/admin/security/audit-logs.md'. DO NOT EDIT -->")
generatorSuffix = []byte("<!-- End generated by 'make docs/admin/security/audit-logs.md'. -->")
)
/*
*
AuditableResourcesMap is derived from audit.AuditableResources
and has the following structure:
{
friendlyResourceName: {
fieldName1: isTracked,
fieldName2: isTracked,
...
},
...
}
*/
type AuditableResourcesMap map[string]map[string]bool
func main() {
flag.StringVar(&auditDocFile, "audit-doc-file", "docs/admin/security/audit-logs.md", "Path to audit log doc file")
flag.BoolVar(&dryRun, "dry-run", false, "Dry run")
flag.Parse()
auditableResourcesMap := readAuditableResources()
doc, err := readAuditDoc()
if err != nil {
log.Fatal("can't read audit doc: ", err)
}
doc, err = updateAuditDoc(doc, auditableResourcesMap)
if err != nil {
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)
}
}
// Transforms audit.AuditableResources to AuditableResourcesMap,
// which uses friendlier language.
func readAuditableResources() AuditableResourcesMap {
auditableResourcesMap := make(AuditableResourcesMap)
for resourceName, resourceFields := range audit.AuditableResources {
friendlyResourceName := strings.Split(resourceName, ".")[2]
fieldNameMap := make(map[string]bool)
for fieldName, action := range resourceFields {
fieldNameMap[fieldName] = action != audit.ActionIgnore
auditableResourcesMap[friendlyResourceName] = fieldNameMap
}
}
return auditableResourcesMap
}
func readAuditDoc() ([]byte, error) {
doc, err := os.ReadFile(auditDocFile)
if err != nil {
return nil, err
}
return doc, nil
}
// Replaces the generated section of the audit doc with one section per
// audit log resource.
func updateAuditDoc(doc []byte, auditableResourcesMap AuditableResourcesMap) ([]byte, error) {
i := bytes.Index(doc, generatorPrefix)
if i < 0 {
return nil, xerrors.New("generator prefix tag not found")
}
tableStartIndex := i + len(generatorPrefix)
if tableStartIndex < len(doc) && doc[tableStartIndex] == '\n' {
tableStartIndex++
}
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')
writeResourceSections(&buffer, auditableResourcesMap, audit.AuditActionMap)
_, _ = buffer.Write(doc[tableEndIndex:])
return buffer.Bytes(), nil
}
// fieldsTableHeader opens every resource's fields table. Markdown tables size
// columns to their content, which puts the Tracked column at a different
// position in each table. HTML width attributes give every table the same
// column widths; they are used instead of inline styles or <colgroup> because
// both GitHub and the docs site sanitizer strip those.
const fieldsTableHeader = `<table width="100%">
<thead><tr><th width="75%">Field</th><th width="25%">Tracked</th></tr></thead>
<tbody>
`
// writeResourceSections writes one section per resource: a heading, the
// audited actions, and a two-column table of fields and whether each is
// tracked. Each heading gives the resource a linkable anchor.
func writeResourceSections(buffer *bytes.Buffer, auditableResourcesMap AuditableResourcesMap, actionMap map[string][]codersdk.AuditAction) {
for _, resourceName := range maps.SortedKeys(auditableResourcesMap) {
readableResourceName := resourceName
// AuditableGroup is really a combination of Group and GroupMember resources
// but we use the label 'Group' in our docs to avoid confusion.
if resourceName == "AuditableGroup" {
readableResourceName = "Group"
}
_, _ = buffer.WriteString("### " + readableResourceName + "\n\n")
var auditActions []string
for _, action := range actionMap[readableResourceName] {
auditActions = append(auditActions, "`"+string(action)+"`")
}
if len(auditActions) > 0 {
_, _ = buffer.WriteString("Actions: " + strings.Join(auditActions, ", ") + "\n\n")
}
_, _ = buffer.WriteString(fieldsTableHeader)
fields := auditableResourcesMap[resourceName]
for _, fieldName := range maps.SortedKeys(fields) {
tracked := "No"
if fields[fieldName] {
tracked = "Yes"
}
_, _ = buffer.WriteString("<tr><td><code>" + html.EscapeString(fieldName) + "</code></td><td>" + tracked + "</td></tr>\n")
}
_, _ = buffer.WriteString("</tbody>\n</table>\n\n")
}
}
func writeAuditDoc(doc []byte) error {
return atomicwrite.File(auditDocFile, doc)
}