AddAuditSupportToNFS [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== AddAuditSupportToNFS ======
  * Student: **[[/ShivankGarg|Shivank Garg]]** (shivank@%%FreeBSD%%.org)
  * Mentor: **[[/AlanSomers|Alan Somers]]** (asomers@%%FreeBSD%%.org)

===== Add audit(4) support to NFS =====

Add audit(4) support to NFS - [[https://summerofcode.withgoogle.com/projects/#5378137010995200|Google Summer of Code 2020 project page]]

===== Differential revisions Submitted =====

^  Differential  ^  Title  ^  Status  ^
| [[https://reviews.freebsd.org/D25263|D25263]] | NFS remove vfs_statfs and vnode_mount macro | [[https://github.com/freebsd/freebsd/commit/ee58a166b5dcab9f035d9c5982396743084f1c9c|Merged]] ✔ |
| <del>D25869</del> [[https://reviews.freebsd.org/D26243|D26243]] | NFSv3 Audit Support | Revision is still in review |

Note:
  - More differential revision has to be submitted for NFSv4 audit support.
  - [[https://github.com/shivankgarg98/NFSAuditTestSuite/|NFSAuditTestSuite]] is reviewed using github and is still under review. It'll come as a %%FreeBSD%% Port (due to dependency on net/libnfs) in the future.

=== Idea of the project: ===
%%FreeBSD%% includes support for security event auditing. Security event auditing permits the selective and fine-grained configurable logging of security-relevant system events for the purpose of post-mortem analysis, intrusion detection, and run-time monitoring. It is important for advanced security and monitoring and is intended to meet the requirements of the Common Criteria(CC)/Common Access protection profile(CAPP) evaluation. The audit subsystem in %%FreeBSD%%, audit(4), can record a variety of system events like user-logins, file system activities, network activities, process creations, etc.

The sysadmin may wish to monitor the filesystem activities within the NFS network.  It will require the sysadmin to run the auditd(8) on each NFS client, and audit trails can be transferred across the network with auditdistd(8). The security officer can review each client’s audit trails to review the NFS activities. This arrangement works perfectly fine in case of secure networks, where the admin has control over the clients as well as servers.

The auditd(8) on the server doesn’t generate any record trails for the NFS activities because the audit works mostly on the syscall level and the NFS server is implemented within the kernel. This makes it bypass the syscall layer and the requests go to the VFS layer.

In case NFS is used on insecure networks, running auditd(8) on each client is not an option as the audit records on the client can be tempered. The audit(4) support to the NFS server is a missing feature for such networks. Thus, The aim of this project is to audit each NFS RPC. This would allow an audit of all NFS activities within the network by just running auditd(8) on the server.

===== Project description & Implementation =====

The ''%%AUDIT_NFSRPC_ENTER%%'' macro checks whether the audit is enabled and ''%%nfs%%'' class is enabled for audit event preselection. If a record is needed, the audit thread allocates ''%%audit record%%'' memory zone associated with RPC request in the ''%%struct kaudit_record *nd_ar%%'' field of ''%%struct nfsrv_descript%%''. Then AUDIT_NFSARG_* macros are used to audit arguments associated with individual RPC service and the FLAGS are set to indicate if the arg has to be included in the audit log stream (as a token). For instance, ''%%AUDIT_NFSARG_NETSOCKADDR(nd, nd->nd_nam)%%'' is used to audit the client socket address associated with the RPC request description. The ''%%AUDIT_NFSRPC_EXIT%%'' macro commits the kernel audit record according to the desired configuration. The ''%%kaudit_to_bsm%%'' does the work of converting the kernel audit record to BSM record and contains individual cases for NFS service to audit the NFS arguments into BSM format tokens.

**NFSv2/3 Audit:** The ''%%AUDIT_NFSRPC_ENTER%%'' and ''%%AUDIT_NFSRPC_EXIT%%'' macros are defined around the nfsrvd_dorpc to audit each NFSv2 and NFSc3 RPC. The ''%%nfsrv3_procsX%%'' (X = 0, 1, 2; depends on number of extra args to NFS service function) maps function pointer array of NFS service to their respective procedure number. The audit event to procedure number mapping is also defined for uniquely identifying the NFSv3 AUDIT event.

**NFSv4 Audit:** The ''%%nfsrvd_compound%%'' RPC request contains various suboperations. It is desired to audit each ''%%nfsrvd_compound%%'' RPC (to get the summary and number of sub-operations associated with the request) and individual sub-operations(which is mostly similar to audit individual NFSv3 RPC) associated with it. The ''%%AUDIT_NFSRPC_ENTER%%'' and ''%%AUDIT_NFSRPC_EXIT%%'' are thus first used to audit the number of suboperations and socket addr in compound RPC (NFSv4 summary record), and then again reusing the ''%%nd_ar%%'' field to audit each sub-operation one-by-one in for loop (as it breaks down an RPC record to subops). The ''%%nfsrv4_auevent[NFSV42_NOPS]%%'' table is used to map NFSv4 procedure number to respective audit event numbers.

===== Test Plan =====

**%%NFSAuditTestSuite%%:** The NFS audit test suite is built on the top net/libnfs port and uses Kyua ATF framework for testing. Note: The %%NFSAuditTestSuite%% design and code is deeply influenced and borrowed from %%RegressionTestSuiteForAuditFramework%% and net/libnfs examples and internal code.
%%NFSAuditTestSuite%% uses async libnfs raw-APIs interface to test individual RPCs. This allows us to test the NFS Audit with high flexibility and helps avoid doing RPC that other than the desired one (as much as possible).

It employs high-level(posix like apis) libnfs API for mounting, etc.(that is doing pre-testing work). Then using raw-api to test the desire RPC and checking the auditpipe output.

===== Work Done =====

  * Added audit support to NFSv2/v3 RPC. [[https://github.com/shivankgarg98/freebsd/tree/user/shivank/nfs_audit|here]]
  * Wrote Test Suite(using net/libnfs) for NFSv3 Audit support. [[https://github.com/shivankgarg98/NFSAuditTestSuite/blob/master/nfsv3-test.c|here]]
  * Added audit support to NFSv4(4, 4.1, 4.2) RPC and Sub-ops. [[https://github.com/shivankgarg98/freebsd/tree/user/shivank/nfsv4_audit|here]]
  * Wrote NFSv4 Test Suite and success/failure tests for NFSv4 operations. [[https://github.com/shivankgarg98/NFSAuditTestSuite/blob/master/nfsv4-test.c|here]]

===== Work Remaining =====

  * To add tests for the additional operations for NFSv4.1 and NFSv4.2.
  * Fix bugs in NFSv4 audit (especially, to found out why nfsrvd_open fails with NFSERR_GRACE?(ideally it should start working after 2-3 mins if it's in recovery%%))%%
  * enhance %%NFSAuditTestSuite%% (like adding more variety of Test-cases, finding and fixing bugs)
  * add NFS error code database to audit for return tokens.
  * enhancing audit support to NFS (like more adding more tokens of relevant info and reducing overheads)

===== Weekly Reports =====

^  Report Email Archive  ^
| [[https://lists.freebsd.org/pipermail/soc-status/2020-June/001220.html|Introduction mail]] |
| [[https://lists.freebsd.org/pipermail/soc-status/2020-June/001223.html|Week 1]] |
| [[https://lists.freebsd.org/pipermail/soc-status/2020-June/001228.html|Week 2]] |
| [[https://lists.freebsd.org/pipermail/soc-status/2020-June/001233.html|Week 3]] |
| [[https://lists.freebsd.org/pipermail/soc-status/2020-July/001235.html|Week 5]] |
| [[https://lists.freebsd.org/pipermail/soc-status/2020-July/001241.html|Week 6]] |
| [[https://lists.freebsd.org/pipermail/soc-status/2020-July/001245.html|Week 7]] |
| [[https://lists.freebsd.org/pipermail/soc-status/2020-July/001248.html|Week 8]] |
| [[https://lists.freebsd.org/pipermail/soc-status/2020-August/001249.html|Week 9-10]] |
| [[https://lists.freebsd.org/pipermail/soc-status/2020-August/001253.html|Week 11]] |
| [[https://lists.freebsd.org/pipermail/soc-status/2020-August/001254.html|Week 12]] |

===== Please check this branch for the code =====
  * NFSv2 and NFSv3 Audit Support - https://github.com/shivankgarg98/freebsd/tree/user/shivank/nfs_audit
  * NFSv4 Audit Support feature branch - https://github.com/shivankgarg98/freebsd/tree/user/shivank/nfsv4_audit
  * %%NFSAuditTestSuite%% - https://github.com/shivankgarg98/NFSAuditTestSuite

=== Compare File Changed (links for quick lookup) ===
  * [[https://github.com/freebsd/freebsd/compare/master...shivankgarg98:user/shivank/nfs_audit|Compare NFSv3 audit file changes wrt FreeBSD HEAD]]
  * [[https://github.com/freebsd/freebsd/compare/master...shivankgarg98:user/shivank/nfsv4_audit|Compare NFSv4 audit file changes/addition wrt FreeBSD HEAD]]

===== Useful links =====
  * [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/audit.html|Security Event Auditing]]
  * [[https://www.freebsd.org/doc/handbook/network-nfs.html|Network File System]]
  * [[https://github.com/freebsd/freebsd/tree/master/tests/sys/audit|Audit TestSuite]]
  * [[https://github.com/sahlberg/libnfs|libnfs library]]

----

{{tag>Gsoc}}