Package: auditmatica
auditmaticaAboutAuditArchivematicauser activities via nginx access logs.Overviewauditmaticais intended to facilitate auditing of user activities in
Archivematica and the Archivematica Storage Service. It uses nginx access logs
as its data source, and outputs either logs inCommon Event Format (CEF)or a JSON overview of user activities.Usageauditmaticahas two subcommands,write-cefandoverview.Usage: auditmatica [OPTIONS] COMMAND [ARGS]...

  Auditmatica: Archivematica auditing package

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  overview   Print overview of user activities from nginx access log.
  write-cef  Write Common Event Format (CEF) log from nginx access log.write-cefTo write CEF events, use thewrite-cefsubcommand. E.g.:auditmaticawrite-cef/path/to/nginx/access.logorcat/var/log/nginx/access.log|auditmaticawrite-cefCEF is a widely used standard for network and security analysis. CEF events
can be sent to applications for review, monitoring, and visualization via a
file or over syslog. CEF events written byauditmaticainclude an event name,
signature (unique identifier), and severity level (0-10), which are determined
based on details from the nginx access log such as URL, HTTP method, and HTTP
return code.A sample CEF event written byauditmaticalooks like the following:CEF:0|Artefactual Systems, Inc.|Archivematica|hosted|16|AIP downloaded from Archival Storage|3|cs1Label=requestClientApplication cs1="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0" rt=Jan 13 2021 20:01:33 requestMethod=GET request=/archival-storage/download/aip/8fa54cfc-f5c5-4673-b44e-fc514496bad7/ src=172.19.0.1 suser=test msg=UUID:8fa54cfc-f5c5-4673-b44e-fc514496bad7For a comprehensive list of Archivematica CEF events, seeIMPLEMENTATION.md.For more details on CEF, see theCEF specification.This command accepts several optional arguments:Usage: auditmatica write-cef [OPTIONS] [LOG]

  Write Common Event Format (CEF) log from nginx access log.

Options:
  -o, --output PATH       Filepath for output CEF file (default=None, print to
                          stdout)

  -s, --syslog            Write CEF events to syslog instead of file
  --syslog-address TEXT   Address for syslog connection (default='/dev/log')
  --syslog-facility TEXT  Facility for syslog messages (default='USER')
  --syslog-port INTEGER   Port for remote syslog connections
  --ss-base-url TEXT      Override the Storage Service URL to scan for
                          (default='http://127.0.0.1:62081')

  --suppress              Suppress log lines that do not map to a specific
                          event instead of reverting to default event

  -v, --verbose           Enable verbose error message reporting
  --help                  Show this message and exit.Storage Serviceauditmaticalooks for Storage Service events in the nginx access log by
checking each URL to determine if it begins with the expected base URL of the
Storage Service. By default, this ishttp://127.0.0.1:62081.To override the Storage Service URL to scan for, use--ss-base-url. E.g.:auditmatica --ss-base-url http://archivematica.example.com:8000OutputBy default,auditmaticawrites CEF events to stdout and some end-user facing
messages to stderr.To write CEF events to a file, use the-o/--outputoption to specify a
filepath for the output file. E.g.:auditmatica write-cef /path/to/nginx/access.log --output my-output-file.logTo write CEF events tosyslog, use the-s/--syslogoption. By
default, this will write syslog messages to/dev/log/using theUSERfacility. The--syslog-address,--syslog-port, and--syslog-facilityoptions can be used to customize the syslog connection. E.g.:auditmaticawrite-cef-s\--syslog-addresslocalhost\--syslog-port514\--syslog-facilitylocal0\/path/to/nginx/access.log--syslog-portwill only be used if an address other than/dev/logis also
passed with--syslog-address.Valid--syslog-facilityvalues arelocal0-local7, which are reserved by
syslog for local use.overviewTo generate a high-level JSON overview of Archivematica user activities, use
theoverviewsubcommand. E.g.:cataccess.log|auditmaticaoverviewUsage: auditmatica overview [OPTIONS] [LOG]

  Write JSON overview of user activities from nginx access log.

Options:
  --ss-base-url TEXT  Override the Storage Service URL to scan for
                      (default='http://127.0.0.1:62081')
  --help              Show this message and exit.Storage Serviceauditmaticalooks for Storage Service events in the nginx access log by
checking each URL to determine if it begins with the expected base URL of the
Storage Service. By default, this ishttp://127.0.0.1:62081.To override the Storage Service URL to scan for, use--ss-base-url. E.g.:auditmatica --ss-base-url http://archivematica.example.com:8000DownloadDownload from GitHub:gitclonehttps://github.com/artefactual-labs/auditmatica.gitInstallGeneralauditmaticarequires Python 3.6+.Change into the cloned directory and install:cdauditmatica/
pipinstall.UsernamesIncluding authenticated usernames inauditmatica's outputs requires some
additional setup:Enable auditing middleware in Archivematica and the Storage Service via
environment variables# Archivematica 1.13+ARCHIVEMATICA_DASHBOARD_DASHBOARD_AUDIT_LOG_MIDDLEWARE:"true"# Storage Service 0.18+SS_AUTH_LOG_MIDDLEWARE:"true"Restart Archivematica and Storage Service servicessudoservicearchivematica-dashboardrestart
sudoservicearchivematica-storage-servicerestartAdd the following configuration to thehttpblock of thenginx.confconfiguration file (likely/etc/nginx/nginx.conf, though this may vary)log_formatmain'$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$http_x_forwarded_for" user=$upstream_http_x_username';access_log"/var/log/nginx/access.log"main;This format must be exact, as it maps directly to a patternauditmaticauses
to parse nginx access log lines with usernames. If anaccess_logis already
specified, replace it or name it something other thanmain. Theaccess_logpath (by default/var/log/nginx/access.log) can be changed as needed.Optionally, addproxy_hide_header x-username;to the nginxserverblocks
to prevent the authenticated username from being sent back with each response
to the client device.Restart nginx service:sudoservicenginxrestartIf the above is configured correctly, the resulting nginx access log lines
should look as follows:172.10.5.1 - - [13/Jan/2021:19:53:10 +0000] "GET /backlog/download/2e28b8a9-351c-4da7-92d2-837ac04cd2d9/ HTTP/1.1" 200 19436360 "http://127.0.0.1:62080/backlog/" "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0" "-" user=testDevelopmentFor development, it may be useful to installauditmaticawithpip install -e ., which will apply changes made to the source code
immediately.To run all tests with tox:toxOr run tests directly with pytest:pipinstall-rrequirements/test.txt
pytest