From e3a5812bfbd374b5d7d3aa0771d76cf278e4c975 Mon Sep 17 00:00:00 2001 From: Alexandre Pujol Date: Wed, 25 Sep 2024 23:17:44 +0100 Subject: [PATCH] doc: add man page for aa-log. --- Makefile | 15 ++++-- dists/apparmor.d.spec | 2 + root/usr/share/man/man8/aa-log.8 | 79 ++++++++++++++++++++++++++++++ root/usr/share/man/man8/aa-log.md | 80 +++++++++++++++++++++++++++++++ 4 files changed, 173 insertions(+), 3 deletions(-) create mode 100644 root/usr/share/man/man8/aa-log.8 create mode 100644 root/usr/share/man/man8/aa-log.md diff --git a/Makefile b/Makefile index 85a4a719..88febbb5 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ PKGDEST := /tmp/pkg PKGNAME := apparmor.d P = $(filter-out dpkg,$(notdir $(wildcard ${BUILD}/apparmor.d/*))) -.PHONY: all build enforce full install local $(P) pkg dpkg rpm tests lint clean +.PHONY: all build enforce full install local $(P) pkg dpkg rpm tests lint man docs serve clean all: build @./${BUILD}/prebuild --complain @@ -24,7 +24,7 @@ enforce: build full: build @./${BUILD}/prebuild --complain --full -ROOT = $(shell find "${BUILD}/root" -type f -printf "%P\n") +ROOT = $(shell find "${BUILD}/root" -type f -not -name "*.md" -printf "%P\n") PROFILES = $(shell find "${BUILD}/apparmor.d" -type f -printf "%P\n") DISABLES = $(shell find "${BUILD}/apparmor.d" -type l -printf "%P\n") install: @@ -56,7 +56,7 @@ local: ABSTRACTIONS = $(shell find ${BUILD}/apparmor.d/abstractions/ -type f -printf "%P\n") TUNABLES = $(shell find ${BUILD}/apparmor.d/tunables/ -type f -printf "%P\n") $(P): - @[ -f ${BUILD}/aa-log ] || exit 0; install -Dm755 ${BUILD}/aa-log ${DESTDIR}/usr/bin/aa-log + @install -Dm0755 ${BUILD}/aa-log ${DESTDIR}/usr/bin/aa-log @for file in ${ABSTRACTIONS}; do \ install -Dm0644 "${BUILD}/apparmor.d/abstractions/$${file}" "${DESTDIR}/etc/apparmor.d/abstractions/$${file}"; \ done; @@ -99,6 +99,15 @@ lint: tests/packer/init/init.sh tests/packer/src/aa-update tests/packer/init/clean.sh \ debian/${PKGNAME}.postinst debian/${PKGNAME}.postrm +man: + pandoc -t man -s -o root/usr/share/man/man8/aa-log.8 root/usr/share/man/man8/aa-log.md + +docs: + ENABLED_GIT_REVISION_DATE=false MKDOCS_OFFLINE=true mkdocs build --strict + +serve: + ENABLED_GIT_REVISION_DATE=false MKDOCS_OFFLINE=false mkdocs serve + clean: @rm -rf \ debian/.debhelper debian/debhelper* debian/*.debhelper debian/${PKGNAME} \ diff --git a/dists/apparmor.d.spec b/dists/apparmor.d.spec index b00b12ec..339d8803 100644 --- a/dists/apparmor.d.spec +++ b/dists/apparmor.d.spec @@ -51,4 +51,6 @@ systemctl is-active -q apparmor && systemctl reload apparmor ||: %dir /usr/share/zsh/site-functions /usr/share/zsh/site-functions/_aa-log.zsh +%doc %{_mandir}/man8/aa-log.8.gz + %changelog diff --git a/root/usr/share/man/man8/aa-log.8 b/root/usr/share/man/man8/aa-log.8 new file mode 100644 index 00000000..42c9a356 --- /dev/null +++ b/root/usr/share/man/man8/aa-log.8 @@ -0,0 +1,79 @@ +.\" Automatically generated by Pandoc 3.1.9 +.\" +.TH "aa-log" "8" "September 2024" "" "" +.SH NAME +aa-log \[em] Review AppArmor generated messages in a colorful way. +.SH SYNOPSIS +\f[B]aa-log\f[R] [\f[I]options\&...\f[R]] [\f[I]profile\f[R]] +.SH DESCRIPTION +Review AppArmor generated messages in a colourful way. +Support logs from \f[I]auditd\f[R], \f[I]systemd\f[R], \f[I]syslog\f[R] +as well as \f[I]dbus session\f[R] events. +.PP +It can be given an optional profile name to filter the output with. +.PP +It can be used to generate AppArmor rules from the logs and it therefore +an alternative to \f[CR]aa-logprof(8)\f[R]. +The generated rules should be manually reviewed and inserted into the +profile. +.PP +Default logs are read from \f[CR]/var/log/audit/audit.log\f[R]. +Other files in \f[CR]/var/log/audit/\f[R] can easily be checked: +\f[B]aa-log -f 1\f[R] parses \f[CR]audit.log.1\f[R] +.SH OPTIONS +\f[B]aa-log\f[R] [\f[I]options\&...\f[R]] [\f[I]profile\f[R]] +.TP +[\f[I]profile\f[R]] +Optional profile name to filter the output with. +.TP +\f[CR]--file\f[R], \f[CR]-f\f[R] +Set a logfile or a suffix to the default log file. +.TP +\f[CR]--systemd\f[R], \f[CR]-s\f[R] +Parse systemd logs from journalctl. +Provides all AppArmor logs since the last boot. +.TP +\f[CR]--rules\f[R], \f[CR]-r\f[R] +Convert the log into AppArmor rules. +.TP +\f[CR]--raw\f[R], \f[CR]-R\f[R] +Print the raw log without any formatting. +Useful for reporting logs. +.TP +\f[CR]--help\f[R], \f[CR]-h\f[R] +Print the program usage. +.SH USAGE +To read the AppArmor log from \f[CR]/var/log/audit/audit.log\f[R]: +.IP +.EX +aa-log +.EE +.PP +To optionally filter a given profile name: +\f[CR]aa-log \f[R] (your shell will autocomplete the +profile name): +.IP +.EX +$ aa-log dnsmasq +DENIED dnsmasq open /proc/sys/kernel/osrelease comm=dnsmasq requested_mask=r denied_mask=r +DENIED dnsmasq open /proc/1/environ comm=dnsmasq requested_mask=r denied_mask=r +DENIED dnsmasq open /proc/cmdline comm=dnsmasq requested_mask=r denied_mask=r +.EE +.PP +To generate AppArmor rule: +.IP +.EX +$ aa-log -r dnsmasq +profile dnsmasq { + \[at]{PROC}/\[at]{pid}/environ r, + \[at]{PROC}/cmdline r, + \[at]{PROC}/sys/kernel/osrelease r, +} +.EE +.SH SEE ALSO +\f[CR]aa-logprof(8)\f[R], \f[CR]apparmor(7)\f[R], +\f[CR]apparmor.d(5)\f[R], \f[CR]aa-genprof(1)\f[R], +\f[CR]aa-enforce(1)\f[R], \f[CR]aa-complain(1)\f[R], +\f[CR]aa-disable(1)\f[R], and https://apparmor.pujol.io. +.SH AUTHORS +aa-log was written by Alexandre Pujol (alexandre\[at]pujol.io). diff --git a/root/usr/share/man/man8/aa-log.md b/root/usr/share/man/man8/aa-log.md new file mode 100644 index 00000000..0b7fe8af --- /dev/null +++ b/root/usr/share/man/man8/aa-log.md @@ -0,0 +1,80 @@ +% aa-log(8) +% aa-log was written by Alexandre Pujol (alexandre@pujol.io) +% September 2024 + +# NAME + +aa-log — Review AppArmor generated messages in a colorful way. + +# SYNOPSIS + +**aa-log** [*options…*] [*profile*] + +# DESCRIPTION + +Review AppArmor generated messages in a colourful way. Support logs from *auditd*, *systemd*, *syslog* as well as *dbus session* events. + +It can be given an optional profile name to filter the output with. + +It can be used to generate AppArmor rules from the logs and it therefore an alternative to `aa-logprof(8)`. The generated rules should be manually reviewed and inserted into the profile. + +Default logs are read from `/var/log/audit/audit.log`. Other files in `/var/log/audit/` can easily be checked: **aa-log -f 1** parses `audit.log.1` + +# OPTIONS + +**aa-log** [*options…*] [*profile*] + +[*profile*] + +: Optional profile name to filter the output with. + +`--file`, `-f` + +: Set a logfile or a suffix to the default log file. + +`--systemd`, `-s` + +: Parse systemd logs from journalctl. Provides all AppArmor logs since the last boot. + +`--rules`, `-r` + +: Convert the log into AppArmor rules. + +`--raw`, `-R` + +: Print the raw log without any formatting. Useful for reporting logs. + +`--help`, `-h` + +: Print the program usage. + + +# USAGE + +To read the AppArmor log from `/var/log/audit/audit.log`: +```sh +aa-log +``` + +To optionally filter a given profile name: `aa-log ` (your shell will autocomplete the profile name): +``` +$ aa-log dnsmasq +DENIED dnsmasq open /proc/sys/kernel/osrelease comm=dnsmasq requested_mask=r denied_mask=r +DENIED dnsmasq open /proc/1/environ comm=dnsmasq requested_mask=r denied_mask=r +DENIED dnsmasq open /proc/cmdline comm=dnsmasq requested_mask=r denied_mask=r +``` + +To generate AppArmor rule: +``` +$ aa-log -r dnsmasq +profile dnsmasq { + @{PROC}/@{pid}/environ r, + @{PROC}/cmdline r, + @{PROC}/sys/kernel/osrelease r, +} +``` + +# SEE ALSO + +`aa-logprof(8)`, `apparmor(7)`, `apparmor.d(5)`, `aa-genprof(1)`, `aa-enforce(1)`, `aa-complain(1)`, `aa-disable(1)`, and +https://apparmor.pujol.io.