diff --git a/README b/README index fd903645e6de..8e948882f470 100644 --- a/README +++ b/README @@ -1,18 +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 -There are several guides for kernel developers and users. These guides can -be rendered in a number of formats, like HTML and PDF. Please read -Documentation/admin-guide/README.rst first. +The original Linux Kernel README file: +* https://github.com/linux-audit/audit-kernel/blob/main/README.orig -In order to build the documentation, use ``make htmldocs`` or -``make pdfdocs``. The formatted documentation can also be read online at: +The Linux Kernel audit subsystem README.md file: +* https://github.com/linux-audit/audit-kernel/blob/main/README.md - https://www.kernel.org/doc/html/latest/ - -There are various text files in the Documentation/ subdirectory, -several of them using the reStructuredText markup notation. - -Please read the Documentation/process/changes.rst file, as it contains the -requirements for building and running the kernel, and information about -the problems which may result by upgrading your kernel. +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 000000000000..0ac5453d542a --- /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 000000000000..669ac7c32292 --- /dev/null +++ b/README.orig @@ -0,0 +1,18 @@ +Linux kernel +============ + +There are several guides for kernel developers and users. These guides can +be rendered in a number of formats, like HTML and PDF. Please read +Documentation/admin-guide/README.rst first. + +In order to build the documentation, use ``make htmldocs`` or +``make pdfdocs``. The formatted documentation can also be read online at: + + https://www.kernel.org/doc/html/latest/ + +There are various text files in the Documentation/ subdirectory, +several of them using the Restructured Text markup notation. + +Please read the Documentation/process/changes.rst file, as it contains the +requirements for building and running the kernel, and information about +the problems which may result by upgrading your kernel. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000000..07836ff5f438 --- /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