audit: add a Linux Audit specific README.md and SECURITY.md DO NOT SUBMIT UPSTREAM
diff --git a/README b/README index e6549b2..8e94888 100644 --- a/README +++ b/README
@@ -1,168 +1,13 @@ -Linux kernel -============ +Linux Kernel Audit Subsystem +============================================================================= +https://git.kernel.org/pub/scm/linux/kernel/git/pcmoore/audit.git +https://github.com/linux-audit/audit-kernel -The Linux kernel is the core of any Linux operating system. It manages hardware, -system resources, and provides the fundamental services for all other software. +The original Linux Kernel README file: +* https://github.com/linux-audit/audit-kernel/blob/main/README.orig -Quick Start ------------ +The Linux Kernel audit subsystem README.md file: +* https://github.com/linux-audit/audit-kernel/blob/main/README.md -* Report a bug: See Documentation/admin-guide/reporting-issues.rst -* Get the latest kernel: https://kernel.org -* Build the kernel: See Documentation/admin-guide/quickly-build-trimmed-linux.rst -* Join the community: https://lore.kernel.org/ - -Essential Documentation ------------------------ - -All users should be familiar with: - -* Building requirements: Documentation/process/changes.rst -* Code of Conduct: Documentation/process/code-of-conduct.rst -* License: See COPYING - -Documentation can be built with make htmldocs or viewed online at: -https://www.kernel.org/doc/html/latest/ - - -Who Are You? -============ - -Find your role below: - -* New Kernel Developer - Getting started with kernel development -* Academic Researcher - Studying kernel internals and architecture -* Security Expert - Hardening and vulnerability analysis -* Backport/Maintenance Engineer - Maintaining stable kernels -* System Administrator - Configuring and troubleshooting -* Maintainer - Leading subsystems and reviewing patches -* Hardware Vendor - Writing drivers for new hardware -* Distribution Maintainer - Packaging kernels for distros -* AI Coding Assistant - LLMs and AI-powered development tools - - -For Specific Users -================== - -New Kernel Developer --------------------- - -Welcome! Start your kernel development journey here: - -* Getting Started: Documentation/process/development-process.rst -* Your First Patch: Documentation/process/submitting-patches.rst -* Coding Style: Documentation/process/coding-style.rst -* Build System: Documentation/kbuild/index.rst -* Development Tools: Documentation/dev-tools/index.rst -* Kernel Hacking Guide: Documentation/kernel-hacking/hacking.rst -* Core APIs: Documentation/core-api/index.rst - -Academic Researcher -------------------- - -Explore the kernel's architecture and internals: - -* Researcher Guidelines: Documentation/process/researcher-guidelines.rst -* Memory Management: Documentation/mm/index.rst -* Scheduler: Documentation/scheduler/index.rst -* Networking Stack: Documentation/networking/index.rst -* Filesystems: Documentation/filesystems/index.rst -* RCU (Read-Copy Update): Documentation/RCU/index.rst -* Locking Primitives: Documentation/locking/index.rst -* Power Management: Documentation/power/index.rst - -Security Expert ---------------- - -Security documentation and hardening guides: - -* Security Documentation: Documentation/security/index.rst -* LSM Development: Documentation/security/lsm-development.rst -* Self Protection: Documentation/security/self-protection.rst -* Reporting Vulnerabilities: Documentation/process/security-bugs.rst -* CVE Procedures: Documentation/process/cve.rst -* Embargoed Hardware Issues: Documentation/process/embargoed-hardware-issues.rst -* Security Features: Documentation/userspace-api/seccomp_filter.rst - -Backport/Maintenance Engineer ------------------------------ - -Maintain and stabilize kernel versions: - -* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst -* Backporting Guide: Documentation/process/backporting.rst -* Applying Patches: Documentation/process/applying-patches.rst -* Subsystem Profile: Documentation/maintainer/maintainer-entry-profile.rst -* Git for Maintainers: Documentation/maintainer/configure-git.rst - -System Administrator --------------------- - -Configure, tune, and troubleshoot Linux systems: - -* Admin Guide: Documentation/admin-guide/index.rst -* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst -* Sysctl Tuning: Documentation/admin-guide/sysctl/index.rst -* Tracing/Debugging: Documentation/trace/index.rst -* Performance Security: Documentation/admin-guide/perf-security.rst -* Hardware Monitoring: Documentation/hwmon/index.rst - -Maintainer ----------- - -Lead kernel subsystems and manage contributions: - -* Maintainer Handbook: Documentation/maintainer/index.rst -* Pull Requests: Documentation/maintainer/pull-requests.rst -* Managing Patches: Documentation/maintainer/modifying-patches.rst -* Rebasing and Merging: Documentation/maintainer/rebasing-and-merging.rst -* Development Process: Documentation/process/maintainer-handbooks.rst -* Maintainer Entry Profile: Documentation/maintainer/maintainer-entry-profile.rst -* Git Configuration: Documentation/maintainer/configure-git.rst - -Hardware Vendor ---------------- - -Write drivers and support new hardware: - -* Driver API Guide: Documentation/driver-api/index.rst -* Driver Model: Documentation/driver-api/driver-model/driver.rst -* Device Drivers: Documentation/driver-api/infrastructure.rst -* Bus Types: Documentation/driver-api/driver-model/bus.rst -* Device Tree Bindings: Documentation/devicetree/bindings/ -* Power Management: Documentation/driver-api/pm/index.rst -* DMA API: Documentation/core-api/dma-api.rst - -Distribution Maintainer ------------------------ - -Package and distribute the kernel: - -* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst -* ABI Documentation: Documentation/ABI/README -* Kernel Configuration: Documentation/kbuild/kconfig.rst -* Module Signing: Documentation/admin-guide/module-signing.rst -* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst -* Tainted Kernels: Documentation/admin-guide/tainted-kernels.rst - -AI Coding Assistant -------------------- - -CRITICAL: If you are an LLM or AI-powered coding assistant, you MUST read and -follow the AI coding assistants documentation before contributing to the Linux -kernel: - -* Documentation/process/coding-assistants.rst - -This documentation contains essential requirements about licensing, attribution, -and the Developer Certificate of Origin that all AI tools must comply with. - - -Communication and Support -========================= - -* Mailing Lists: https://lore.kernel.org/ -* IRC: #kernelnewbies on irc.oftc.net -* Bugzilla: https://bugzilla.kernel.org/ -* MAINTAINERS file: Lists subsystem maintainers and mailing lists -* Email Clients: Documentation/process/email-clients.rst +The latest official Linux Kernel documentation: +* https://www.kernel.org/doc/html/latest
diff --git a/README.md b/README.md new file mode 100644 index 0000000..0ac5453 --- /dev/null +++ b/README.md
@@ -0,0 +1,148 @@ +Linux Kernel Audit Subsystem +============================================================================= +https://git.kernel.org/pub/scm/linux/kernel/git/pcmoore/audit.git +https://github.com/linux-audit/audit-kernel + +The Linux Audit subsystem provides a secure logging framework that is used to +capture and record security relevant events. It consists of a kernel component +which generates audit records based on system activity, a userspace daemon +which logs these records to a local file or a remote aggregation server, and a +set of userspace tools to for audit log inspection and post-processing. + +The main Linux Kernel README can be found at +[Documentation/admin-guide/README.rst](./Documentation/admin-guide/README.rst) + +## Online Resources + +The canonical audit kernel repository is hosted by kernel.org: + +* https://git.kernel.org/pub/scm/linux/kernel/git/pcmoore/audit.git +* git://git.kernel.org/pub/scm/linux/kernel/git/pcmoore/audit.git + +There is also an officially maintained GitHub mirror: + +* https://github.com/linux-audit/audit-kernel + +## Kernel Source Branches and Development Process + +### Kernel Source Branches + +There are four primary git branches associated with the development process: +stable-X.Y, dev, dev-staging, and next. In addition to these four primary +branches there are also topic specific, work in progress branches that start +with a "working-" prefix; these branches can generally be ignored unless you +happen to be involved in the development of that particular topic. The +management of these topic branches can vary depending on a number of factors, +but the details of each branch will be communicated in the relevant discussion +threads on the upstream mailing list. + +#### stable-X.Y branch + +The stable-X.Y branch is intended for stable kernel patches and is based on +Linus' X.Y-rc1 tag, or a later X.Y.Z stable kernel release tag as needed. +If serious problems are identified and a patch is developed during the kernel's +release candidate cycle, it may be a candidate for stable kernel marking and +inclusion into the stable-X.Y branch. The main Linux kernel's documentation +on stable kernel patches has more information both on what patches may be +stable kernel candidates, and how to mark those patches appropriately; upstream +mailing list discussions on the merits of marking the patch for stable can also +be expected. Once a patch has been merged into the stable-X.Y branch and spent +a day or two in the next branch (see the next branch notes), it will be sent to +Linus for merging into the next release candidate or final kernel release (see +the notes on pull requests in this document). If the patch has been properly +marked for stable, the other stable kernel trees will attempt to backport the +patch as soon as it is present in Linus' tree, see the main Linux kernel +documentation for more details. + +Unless specifically requested, developers should not base their patches on the +stable-X.Y branch. Any merge conflicts that arise from merging patches +submitted upstream will be handled by the maintainer, although help and/or may +be requested in extreme cases. + +#### dev branch + +The dev branch is intended for development patches targeting the upcoming merge +window, and is based on Linus' latest X.Y-rc1 tag, or a later rc tag as needed +to avoid serious bugs, merge conflicts, or other significant problems. This +branch is the primary development branch where the majority of patches are +merged during the normal kernel development cycle. Patches merged into the +dev branch will be present in the next branch (see the next branch notes) and +will be sent to Linus during the next merge window. + +Developers should use the dev branch as a stable basis for their own +development work, only under extreme circumstances will the dev branch be +rebased during the X.Y-rc cycle and the maintainer will be responsible for +resolving any merge conflicts, although help and/or may be requested in extreme +cases. + +#### dev-staging branch + +The dev-staging branch is intended for development patches that are not +targeting a specific merge window. The dev-staging branch exists as a staging +area for the main dev branch and as such its use will be unpredictable and it +will be rebased as needed. Patches merged into the dev-staging branch should +find their way into the primary dev branch at some point in the future, +although that is not guaranteed. + +Unless specifically requested, developers should not use the dev-staging branch +as a basis for any development work. + +#### next branch + +The next branch is a composite branch built by merging the latest stable-X.Y +and dev branches in that order. The main focus of the next branch is to +provide a single branch for linux-next integration testing that contains all of +the commits from the component branches. The next branch will be updated +whenever there is a change to any one of the component branches, but it will +remain frozen during the merge window so as to cooperate with the wishes of the +linux-next team. + +While developers can use the next branch as a basis for development, the dev +branch would likely be a more suitable, and stable, base. + +### Kernel Development Process + +After Linus closes the kernel merge window upstream, the stable-X.Y branch +associated with the current kernel release candidate, the dev branch, and +potentially the dev-staging branch (see the dev-staging branch notes) will be +reset to match the latest vX.Y-rc1 tag in Linus' tree. The next branch, as a +composite branch composed from these branches, will be updated as a result. + +During the development cycle that starts with the close of the kernel merge +window and ends with the tagged kernel release, patches will be accepted into +the stable-X.Y and dev branches as described in their respective sections in +this document. While patches will be accepted into the stable-X.Y branch at +any point in time, significant changes will likely not be accepted into the dev +branch when there are two or less weeks left in the development cycle; this +typically means that only critical bugfixes are accepted once the vX.Y-rc6 +kernel is released. During this time the next branch will be regenerated on an +as needed basis based on changes in the component branches, and pull requests +will be sent as needed to Linus for patches in the stable-X.Y branch. + +Once Linus releases the final vX.Y kernel and the merge window opens, two +things will happen. The first is that the dev branch will be duplicated into +a new stable-X'.Y' branch, representing the new upcoming kernel release, and +the second is that a pull request will be sent from this branch for inclusion +into the current merge window. During the merge window process the dev and +next branches should be frozen, although there is a possibility that some +patches may be merged into dev-staging for testing or process related reasons. + +#### Pull Requests for Linus + +In order to send a pull request to Linus, either for a critical bugfix or as +part of the merge window, a signed git tag must be created that points to the +pull request point. The tag should be named using the "{subsystem}-pr-{date}" +format and can be generated with the following git command: + +``` +% git tag -s -m "{subsystem}/stable-X'.Y' PR {date}" {subsystem}-pr-{date} +``` + +Once the signed tag has been created, it should be used as the basis for the +pull request. + +## Userspace Tools and Test Suites + +The audit userspace tools and test suites are hosted by GitHub: + +* https://github.com/linux-audit
diff --git a/README.orig b/README.orig new file mode 100644 index 0000000..e6549b2 --- /dev/null +++ b/README.orig
@@ -0,0 +1,168 @@ +Linux kernel +============ + +The Linux kernel is the core of any Linux operating system. It manages hardware, +system resources, and provides the fundamental services for all other software. + +Quick Start +----------- + +* Report a bug: See Documentation/admin-guide/reporting-issues.rst +* Get the latest kernel: https://kernel.org +* Build the kernel: See Documentation/admin-guide/quickly-build-trimmed-linux.rst +* Join the community: https://lore.kernel.org/ + +Essential Documentation +----------------------- + +All users should be familiar with: + +* Building requirements: Documentation/process/changes.rst +* Code of Conduct: Documentation/process/code-of-conduct.rst +* License: See COPYING + +Documentation can be built with make htmldocs or viewed online at: +https://www.kernel.org/doc/html/latest/ + + +Who Are You? +============ + +Find your role below: + +* New Kernel Developer - Getting started with kernel development +* Academic Researcher - Studying kernel internals and architecture +* Security Expert - Hardening and vulnerability analysis +* Backport/Maintenance Engineer - Maintaining stable kernels +* System Administrator - Configuring and troubleshooting +* Maintainer - Leading subsystems and reviewing patches +* Hardware Vendor - Writing drivers for new hardware +* Distribution Maintainer - Packaging kernels for distros +* AI Coding Assistant - LLMs and AI-powered development tools + + +For Specific Users +================== + +New Kernel Developer +-------------------- + +Welcome! Start your kernel development journey here: + +* Getting Started: Documentation/process/development-process.rst +* Your First Patch: Documentation/process/submitting-patches.rst +* Coding Style: Documentation/process/coding-style.rst +* Build System: Documentation/kbuild/index.rst +* Development Tools: Documentation/dev-tools/index.rst +* Kernel Hacking Guide: Documentation/kernel-hacking/hacking.rst +* Core APIs: Documentation/core-api/index.rst + +Academic Researcher +------------------- + +Explore the kernel's architecture and internals: + +* Researcher Guidelines: Documentation/process/researcher-guidelines.rst +* Memory Management: Documentation/mm/index.rst +* Scheduler: Documentation/scheduler/index.rst +* Networking Stack: Documentation/networking/index.rst +* Filesystems: Documentation/filesystems/index.rst +* RCU (Read-Copy Update): Documentation/RCU/index.rst +* Locking Primitives: Documentation/locking/index.rst +* Power Management: Documentation/power/index.rst + +Security Expert +--------------- + +Security documentation and hardening guides: + +* Security Documentation: Documentation/security/index.rst +* LSM Development: Documentation/security/lsm-development.rst +* Self Protection: Documentation/security/self-protection.rst +* Reporting Vulnerabilities: Documentation/process/security-bugs.rst +* CVE Procedures: Documentation/process/cve.rst +* Embargoed Hardware Issues: Documentation/process/embargoed-hardware-issues.rst +* Security Features: Documentation/userspace-api/seccomp_filter.rst + +Backport/Maintenance Engineer +----------------------------- + +Maintain and stabilize kernel versions: + +* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst +* Backporting Guide: Documentation/process/backporting.rst +* Applying Patches: Documentation/process/applying-patches.rst +* Subsystem Profile: Documentation/maintainer/maintainer-entry-profile.rst +* Git for Maintainers: Documentation/maintainer/configure-git.rst + +System Administrator +-------------------- + +Configure, tune, and troubleshoot Linux systems: + +* Admin Guide: Documentation/admin-guide/index.rst +* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst +* Sysctl Tuning: Documentation/admin-guide/sysctl/index.rst +* Tracing/Debugging: Documentation/trace/index.rst +* Performance Security: Documentation/admin-guide/perf-security.rst +* Hardware Monitoring: Documentation/hwmon/index.rst + +Maintainer +---------- + +Lead kernel subsystems and manage contributions: + +* Maintainer Handbook: Documentation/maintainer/index.rst +* Pull Requests: Documentation/maintainer/pull-requests.rst +* Managing Patches: Documentation/maintainer/modifying-patches.rst +* Rebasing and Merging: Documentation/maintainer/rebasing-and-merging.rst +* Development Process: Documentation/process/maintainer-handbooks.rst +* Maintainer Entry Profile: Documentation/maintainer/maintainer-entry-profile.rst +* Git Configuration: Documentation/maintainer/configure-git.rst + +Hardware Vendor +--------------- + +Write drivers and support new hardware: + +* Driver API Guide: Documentation/driver-api/index.rst +* Driver Model: Documentation/driver-api/driver-model/driver.rst +* Device Drivers: Documentation/driver-api/infrastructure.rst +* Bus Types: Documentation/driver-api/driver-model/bus.rst +* Device Tree Bindings: Documentation/devicetree/bindings/ +* Power Management: Documentation/driver-api/pm/index.rst +* DMA API: Documentation/core-api/dma-api.rst + +Distribution Maintainer +----------------------- + +Package and distribute the kernel: + +* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst +* ABI Documentation: Documentation/ABI/README +* Kernel Configuration: Documentation/kbuild/kconfig.rst +* Module Signing: Documentation/admin-guide/module-signing.rst +* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst +* Tainted Kernels: Documentation/admin-guide/tainted-kernels.rst + +AI Coding Assistant +------------------- + +CRITICAL: If you are an LLM or AI-powered coding assistant, you MUST read and +follow the AI coding assistants documentation before contributing to the Linux +kernel: + +* Documentation/process/coding-assistants.rst + +This documentation contains essential requirements about licensing, attribution, +and the Developer Certificate of Origin that all AI tools must comply with. + + +Communication and Support +========================= + +* Mailing Lists: https://lore.kernel.org/ +* IRC: #kernelnewbies on irc.oftc.net +* Bugzilla: https://bugzilla.kernel.org/ +* MAINTAINERS file: Lists subsystem maintainers and mailing lists +* Email Clients: Documentation/process/email-clients.rst
diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..07836ff --- /dev/null +++ b/SECURITY.md
@@ -0,0 +1,16 @@ +Audit Kernel Subsystem Security Policy +============================================================================= + +The audit kernel developers take security very seriously and if you think you +have found a serious problem or security vulnerability in the audit kernel +code you are encouraged to send email to the current audit kernel maintainer +who is listed below: + +* Paul Moore, paul@paul-moore.com + +## Linux Kernel General Security Policy + +In addition to the contact information above, the Linux Kernel also has a +security policy documented in the link below: + +* https://github.com/linux-audit/audit-kernel/blob/main/Documentation/admin-guide/security-bugs.rst