audit: add a Linux Audit specific README.md and SECURITY.mdHEADmain

DO NOT SUBMIT UPSTREAM

4 files changed, 192 insertions, 15 deletions

diff --git a/README b/README
index fd903645e6de06..8e948882f470d0 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 00000000000000..30b2ebc48364b0
--- /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 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 closes 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 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 00000000000000..669ac7c3229279
--- /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 00000000000000..07836ff5f43854
--- /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