## 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.
171 lines
4.9 KiB
Go
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)
|
|
}
|