diff --git a/contrib/Makefile b/contrib/Makefile index 9cff3cbc104..bd251f6c668 100644 --- a/contrib/Makefile +++ b/contrib/Makefile @@ -28,7 +28,6 @@ SUBDIRS = \ oid2name \ pageinspect \ passwordcheck \ - pg_audit \ pg_buffercache \ pg_freespacemap \ pg_prewarm \ diff --git a/doc/src/sgml/pgaudit.sgml b/doc/src/sgml/pgaudit.sgml deleted file mode 100644 index c7ca65296d4..00000000000 --- a/doc/src/sgml/pgaudit.sgml +++ /dev/null @@ -1,678 +0,0 @@ - - - - pg_audit - - - pg_audit - - - - The pg_audit extension provides detailed session - and/or object audit logging via the standard logging facility. The goal - is to provide the tools needed to produce audit logs required to pass any - government, financial, or ISO certification audit. - - - - An audit is an official inspection of an individual's or organization's - accounts, typically by an independent body. The information gathered by - pg_audit is properly called an audit trail or audit - log. The term audit log is used in this documentation. - - - - Why <literal>pg_audit</>? - - - Basic statement logging can be provided by the standard logging facility - using log_statement = all. This is acceptable for monitoring - and other usages but does not provide the level of detail generally - required for an audit. It is not enough to have a list of all the - operations performed against the database. It must also be possible to - find particular statements that are of interest to an auditor. The - standard logging facility shows what the user requested, while - pg_audit focuses on the details of what happened while - the database was satisfying the request. - - - - For example, an auditor may want to verify that a particular table was - created inside a documented maintenance window. This might seem like a - simple job for grep, but what if you are presented with something like - this (intentionally obfuscated) example: - - - -DO $$ -BEGIN - EXECUTE 'CREATE TABLE import' || 'ant_table (id INT)'; -END $$; - - - - Standard logging will give you this: - - - -LOG: statement: DO $$ -BEGIN - EXECUTE 'CREATE TABLE import' || 'ant_table (id INT)'; -END $$; - - - - It appears that finding the table of interest may require some knowledge - of the code in cases where tables are created dynamically. This is not - ideal since it would be preferrable to just search on the table name. - This is where pg_audit comes in. For the same input, - it will produce this output in the log: - - - -AUDIT: SESSION,33,1,FUNCTION,DO,,,"DO $$ -BEGIN - EXECUTE 'CREATE TABLE import' || 'ant_table (id INT)'; -END $$;" -AUDIT: SESSION,33,2,DDL,CREATE TABLE,TABLE,public.important_table,CREATE TABLE important_table (id INT) - - - - Not only is the DO block logged, but substatement 2 contains - the full text of the CREATE TABLE with the statement type, - object type, and full-qualified name to make searches easy. - - - - When logging SELECT and DML statements, - pg_audit can be configured to log a separate entry for each - relation referenced in a statement. No parsing is required to find all - statements that touch a particular table. In fact, the goal is that the - statement text is provided primarily for deep forensics and should not be - required for an audit. - - - - - Usage Considerations - - - Depending on settings, it is possible for pg_audit to - generate an enormous volume of logging. Be careful to determine - exactly what needs to be audit logged in your environment to avoid - logging too much. - - - - For example, when working in an OLAP environment it would probably not be - wise to audit log inserts into a large fact table. The size of the log - file will likely be many times the actual data size of the inserts because - the log file is expressed as text. Since logs are generally stored with - the OS this may lead to disk space being exhausted very - quickly. In cases where it is not possible to limit audit logging to - certain tables, be sure to assess the performance impact while testing - and allocate plenty of space on the log volume. This may also be true for - OLTP environments. Even if the insert volume is not as high, the - performance impact of audit logging may still noticeably affect latency. - - - - To limit the number of relations audit logged for SELECT - and DML statments, consider using object audit logging - (see ). Object audit logging - allows selection of the relations to be logged allowing for reduction - of the overall log volume. However, when new relations are added they - must be explicitly added to object audit logging. A programmatic - solution where specified tables are excluded from logging and all others - are included may be a good option in this case. - - - - - Settings - - - Settings may be modified only by a superuser. Allowing normal users to - change their settings would defeat the point of an audit log. - - - - Settings can be specified globally (in - postgresql.conf or using - ALTER SYSTEM ... SET), at the database level (using - ALTER DATABASE ... SET), or at the role level (using - ALTER ROLE ... SET). Note that settings are not - inherited through normal role inheritance and SET ROLE will - not alter a user's pg_audit settings. This is a limitation - of the roles system and not inherent to pg_audit. - - - - The pg_audit extension must be loaded in - . Otherwise, an error - will be raised at load time and no audit logging will occur. - - - - - pg_audit.log (string) - - pg_audit.log configuration parameter - - - - - Specifies which classes of statements will be logged by session - audit logging. Possible values are: - - - - - - READ - SELECT and - COPY when the source is a relation or a - query. - - - - - WRITE - INSERT, - UPDATE, DELETE, - TRUNCATE, and COPY when the - destination is a relation. - - - - - FUNCTION - Function calls and - DO blocks. - - - - - ROLE - Statements related to roles and - privileges: GRANT, - REVOKE, - CREATE/ALTER/DROP ROLE. - - - - - DDL - All DDL that is not included - in the ROLE class. - - - - - MISC - Miscellaneous commands, e.g. - DISCARD, FETCH, - CHECKPOINT, VACUUM. - - - - - - Multiple classes can be provided using a comma-separated list and - classes can be subtracted by prefacing the class with a - - sign (see ). - The default is none. - - - - - - pg_audit.log_catalog (boolean) - - pg_audit.log_catalog configuration parameter - - - - - Specifies that session logging should be enabled in the case where all - relations in a statement are in pg_catalog. Disabling this setting - will reduce noise in the log from tools like psql and PgAdmin that query - the catalog heavily. The default is on. - - - - - - pg_audit.log_level (boolean) - - pg_audit.log_level configuration parameter - - - - - Specifies the log level that will be used for log entries (see - for valid levels). - This setting is used for regression testing and may also be useful - to end users for testing or other purposes. It is not intended to - be used in a production environment as it may leak which statements - are being logged to the user. The default is log. - - - - - - pg_audit.log_parameter (boolean) - - pg_audit.log_parameter configuration parameter - - - - - Specifies that audit logging should include the parameters that - were passed with the statement. When parameters are present they will - be included in CSV format after the statement text. The default is - off. - - - - - - pg_audit.log_relation (boolean) - - pg_audit.log_relation configuration parameter - - - - - Specifies whether session audit logging should create a separate - log entry for each relation (TABLE, VIEW, - etc.) referenced in a SELECT or DML - statement. This is a useful shortcut for exhaustive logging - without using object audit logging. The default is - off. - - - - - - pg_audit.log_statement_once (boolean) - - pg_audit.log_statement_once configuration parameter - - - - - Specifies whether logging will include the statement text and - parameters with the first log entry for a statement/substatement - combination or with every entry. Disabling this setting will - result in less verbose logging but may make it more difficult to - determine the statement that generated a log entry, though the - statement/substatement pair along with the process id should suffice - to identify the statement text logged with a previous entry. The - default is off. - - - - - - pg_audit.role (string) - - pg_audit.role configuration parameter - - - - - Specifies the master role to use for object audit logging. Muliple - audit roles can be defined by granting them to the master role. - This allows multiple groups to be in charge of different aspects - of audit logging. There is no default. - - - - - - - - Session Audit Logging - - - Session audit logging provides detailed logs of all statements executed - by a user in the backend. - - - - Configuration - - - Session logging is enabled with the - setting. - - Enable session logging for all DML and DDL and - log all relations in DML statements: - -set pg_audit.log = 'write, ddl'; -set pg_audit.log_relation = on; - - - - - Enable session logging for all commands except MISC and - raise audit log messages as NOTICE: - -set pg_audit.log = 'all, -misc'; -set pg_audit.log_notice = on; - - - - - - Example - - - In this example session audit logging is used for logging - DDL and SELECT statements. Note that the - insert statement is not logged since the WRITE class - is not enabled - - - - SQL: - - -set pg_audit.log = 'read, ddl'; - -create table account -( - id int, - name text, - password text, - description text -); - -insert into account (id, name, password, description) - values (1, 'user1', 'HASH1', 'blah, blah'); - -select * - from account; - - - - Log Output: - - - -AUDIT: SESSION,1,1,DDL,CREATE TABLE,TABLE,public.account,create table account -( - id int, - name text, - password text, - description text -); -AUDIT: SESSION,2,1,READ,SELECT,,,select * - from account - - - - - - Object Auditing - - - Object audit logging logs statements that affect a particular relation. - Only SELECT, INSERT, UPDATE and - DELETE commands are supported. TRUNCATE is not - included because there is no specific privilege for it. - - - - Object audit logging is intended to be a finer-grained replacement for - pg_audit.log = 'read, write'. As such, it may not - make sense to use them in conjunction but one possible scenario would - be to use session logging to capture each statement and then supplement - that with object logging to get more detail about specific relations. - - - - Configuration - - - Object-level audit logging is implemented via the roles system. The - setting defines the role that - will be used for audit logging. A relation (TABLE, - VIEW, etc.) will be audit logged when the audit role has - permissions for the command executed or inherits the permissions from - another role. This allows you to effectively have multiple audit roles - even though there is a single master role in any context. - - - - Set to auditor and - grant SELECT and DELETE privileges on the - account table. Any SELECT or - DELETE statements on account will now be - logged: - - - -set pg_audit.role = 'auditor'; - -grant select, delete - on public.account - to auditor; - - - - - Example - - - In this example object audit logging is used to illustrate how a - granular approach may be taken towards logging of SELECT - and DML statements. Note that logging on the - account table is controlled by column-level permissions, - while logging on account_role_map is table-level. - - - - SQL: - - - -set pg_audit.role = 'auditor'; - -create table account -( - id int, - name text, - password text, - description text -); - -grant select (password) - on public.account - to auditor; - -select id, name - from account; - -select password - from account; - -grant update (name, password) - on public.account - to auditor; - -update account - set description = 'yada, yada'; - -update account - set password = 'HASH2'; - -create table account_role_map -( - account_id int, - role_id int -); - -grant select - on public.account_role_map - to auditor; - -select account.password, - account_role_map.role_id - from account - inner join account_role_map - on account.id = account_role_map.account_id - - - - Log Output: - - - -AUDIT: OBJECT,1,1,READ,SELECT,TABLE,public.account,select password - from account -AUDIT: OBJECT,2,1,WRITE,UPDATE,TABLE,public.account,update account - set password = 'HASH2' -AUDIT: OBJECT,3,1,READ,SELECT,TABLE,public.account,select account.password, - account_role_map.role_id - from account - inner join account_role_map - on account.id = account_role_map.account_id -AUDIT: OBJECT,3,1,READ,SELECT,TABLE,public.account_role_map,select account.password, - account_role_map.role_id - from account - inner join account_role_map - on account.id = account_role_map.account_id - - - - - - Format - - - Audit entries are written to the standard logging facility and contain - the following columns in comma-separated format: - - - - Output is compliant CSV format only if the log line prefix portion - of each log entry is removed. - - - - - - - AUDIT_TYPE - SESSION or - OBJECT. - - - - - STATEMENT_ID - Unique statement ID for this session. - Each statement ID represents a backend call. Statement IDs are - sequential even if some statements are not logged. There may be - multiple entries for a statement ID when more than one relation - is logged. - - - - - SUBSTATEMENT_ID - Sequential ID for each - substatement within the main statement. For example, calling - a function from a query. Substatement IDs are continuous - even if some substatements are not logged. There may be multiple - entries for a substatement ID when more than one relation is logged. - - - - - CLASS - e.g. (READ, - ROLE) (see ). - - - - - COMMAND - e.g. ALTER TABLE, - SELECT. - - - - - OBJECT_TYPE - TABLE, - INDEX, VIEW, etc. - Available for SELECT, DML and most - DDL statements. - - - - - OBJECT_NAME - The fully-qualified object name - (e.g. public.account). Available for SELECT, - DML and most DDL statements. - - - - - STATEMENT - Statement executed on the backend. - - - - - - - Use to add any other fields that - are needed to satisfy your audit log requirements. A typical log line - prefix might be '%m %u %d: ' which would provide the date/time, - user name, and database name for each audit log. - - - - - Caveats - - - - - Object renames are logged under the name they were renamed to. - For example, renaming a table will produce the following result: - - - -ALTER TABLE test RENAME TO test2; - -AUDIT: SESSION,36,1,DDL,ALTER TABLE,TABLE,public.test2,ALTER TABLE test RENAME TO test2 - - - - - - It is possible to have a command logged more than once. For example, - when a table is created with a primary key specified at creation time - the index for the primary key will be logged independently and another - audit log will be made for the index under the create entry. The - multiple entries will however be contained within one statement ID. - - - - - - Autovacuum and Autoanalyze are not logged. - - - - - - Statements that are executed after a transaction enters an aborted state - will not be audit logged. However, the statement that caused the error - and any subsequent statements executed in the aborted transaction will - be logged as ERRORs by the standard logging facility. - - - - - - - Authors - - - Abhijit Menon-Sen ams@2ndQuadrant.com, Ian Barwick ian@2ndQuadrant.com, and David Steele david@pgmasters.net. - - -