Skip to content

Commit aa64b2f

Browse files
pcmoorepcmoore
committed
audit: add a Linux Audit specific README.md and SECURITY.md
DO NOT SUBMIT UPSTREAM
1 parent 7d0a66e commit aa64b2f

File tree

4 files changed

+192
-15
lines changed

4 files changed

+192
-15
lines changed

‎README‎

Lines changed: 10 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,13 @@
1-
Linux kernel
2-
============
1+
Linux Kernel Audit Subsystem
2+
=============================================================================
3+
https://git.kernel.org/pub/scm/linux/kernel/git/pcmoore/audit.git
4+
https://github.com/linux-audit/audit-kernel
35

4-
There are several guides for kernel developers and users. These guides can
5-
be rendered in a number of formats, like HTML and PDF. Please read
6-
Documentation/admin-guide/README.rst first.
6+
The original Linux Kernel README file:
7+
* https://github.com/linux-audit/audit-kernel/blob/main/README.orig
78

8-
In order to build the documentation, use ``make htmldocs`` or
9-
``make pdfdocs``. The formatted documentation can also be read online at:
9+
The Linux Kernel audit subsystem README.md file:
10+
* https://github.com/linux-audit/audit-kernel/blob/main/README.md
1011

11-
https://www.kernel.org/doc/html/latest/
12-
13-
There are various text files in the Documentation/ subdirectory,
14-
several of them using the reStructuredText markup notation.
15-
16-
Please read the Documentation/process/changes.rst file, as it contains the
17-
requirements for building and running the kernel, and information about
18-
the problems which may result by upgrading your kernel.
12+
The latest official Linux Kernel documentation:
13+
* https://www.kernel.org/doc/html/latest

‎README.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
Linux Kernel Audit Subsystem
2+
=============================================================================
3+
https://git.kernel.org/pub/scm/linux/kernel/git/pcmoore/audit.git
4+
https://github.com/linux-audit/audit-kernel
5+
6+
The Linux Audit subsystem provides a secure logging framework that is used to
7+
capture and record security relevant events. It consists of a kernel component
8+
which generates audit records based on system activity, a userspace daemon
9+
which logs these records to a local file or a remote aggregation server, and a
10+
set of userspace tools to for audit log inspection and post-processing.
11+
12+
The main Linux Kernel README can be found at
13+
[Documentation/admin-guide/README.rst](./Documentation/admin-guide/README.rst)
14+
15+
## Online Resources
16+
17+
The canonical audit kernel repository is hosted by kernel.org:
18+
19+
* https://git.kernel.org/pub/scm/linux/kernel/git/pcmoore/audit.git
20+
* git://git.kernel.org/pub/scm/linux/kernel/git/pcmoore/audit.git
21+
22+
There is also an officially maintained GitHub mirror:
23+
24+
* https://github.com/linux-audit/audit-kernel
25+
26+
## Kernel Source Branches and Development Process
27+
28+
### Kernel Source Branches
29+
30+
There are four primary git branches associated with the development process:
31+
stable-X.Y, dev, dev-staging, and next. In addition to these four primary
32+
branches there are also topic specific, work in progress branches that start
33+
with a "working-" prefix; these branches can generally be ignored unless you
34+
happen to be involved in the development of that particular topic. The
35+
management of these topic branches can vary depending on a number of factors,
36+
but the details of each branch will be communicated in the relevant discussion
37+
threads on the upstream mailing list.
38+
39+
#### stable-X.Y branch
40+
41+
The stable-X.Y branch is intended for stable kernel patches and is based on
42+
Linus' X.Y-rc1 tag, or a later X.Y.Z stable kernel release tag as needed.
43+
If serious problems are identified and a patch is developed during the kernel's
44+
release candidate cycle, it may be a candidate for stable kernel marking and
45+
inclusion into the stable-X.Y branch. The main Linux kernel's documentation
46+
on stable kernel patches has more information both on what patches may be
47+
stable kernel candidates, and how to mark those patches appropriately; upstream
48+
mailing list discussions on the merits of marking the patch for stable can also
49+
be expected. Once a patch has been merged into the stable-X.Y branch and spent
50+
a day or two in the next branch (see the next branch notes), it will be sent to
51+
Linus for merging into the next release candidate or final kernel release (see
52+
the notes on pull requests in this document). If the patch has been properly
53+
marked for stable, the other stable kernel trees will attempt to backport the
54+
patch as soon as it is present in Linus' tree, see the main Linux kernel
55+
documentation for more details.
56+
57+
Unless specifically requested, developers should not base their patches on the
58+
stable-X.Y branch. Any merge conflicts that arise from merging patches
59+
submitted upstream will be handled by the maintainer, although help and/or may
60+
be requested in extreme cases.
61+
62+
#### dev branch
63+
64+
The dev branch is intended for development patches targeting the upcoming merge
65+
window, and is based on Linus' latest X.Y-rc1 tag, or a later rc tag as needed
66+
to avoid serious bugs, merge conflicts, or other significant problems. This
67+
branch is the primary development branch where the majority of patches are
68+
merged during the normal kernel development cycle. Patches merged into the
69+
dev branch will be present in the next branch (see the next branch notes) and
70+
will be sent to Linus during the next merge window.
71+
72+
Developers should use the dev branch as a stable basis for their own
73+
development work, only under extreme circumstances will the dev branch be
74+
rebased during the X.Y-rc cycle and the maintainer will be responsible for
75+
resolving any merge conflicts, although help and/or may be requested in extreme
76+
cases.
77+
78+
#### dev-staging branch
79+
80+
The dev-staging branch is intended for development patches that are not
81+
targeting a specific merge window. The dev-staging branch exists as a staging
82+
area for the main dev branch and as such its use will be unpredictable and it
83+
will be rebased as needed. Patches merged into the dev-staging branch should
84+
find their way into the primary dev branch at some point in the future,
85+
although that is not guaranteed.
86+
87+
Unless specifically requested, developers should not use the dev-staging branch
88+
as a basis for any development work.
89+
90+
#### next branch
91+
92+
The next branch is a composite branch built by merging the latest stable-X.Y
93+
and dev branches in that order. The main focus of the next branch is to
94+
provide a single branch for linux-next integration testing that contains all of
95+
the commits from the component branches. The next branch will be updated
96+
whenever there is a change to any one of the component branches, but it will
97+
remain frozen during the merge window so as to cooperate with the wishes of the
98+
linux-next team.
99+
100+
While developers can use the next branch as a basis for development, the dev
101+
branch would likely be a more suitable, and stable, base.
102+
103+
### Kernel Development Process
104+
105+
After Linus closes the kernel merge window upstream, the stable-X.Y branch
106+
associated with the current kernel release candidate, the dev branch, and
107+
potentially the dev-staging branch (see the dev-staging branch notes) will be
108+
reset to match the latest vX.Y-rc1 tag in Linus' tree. The next branch, as a
109+
composite branch composed from these branches, will be updated as a result.
110+
111+
During the development cycle that starts with the close of the kernel merge
112+
window and ends with the tagged kernel release, patches will be accepted into
113+
the stable-X.Y and dev branches as described in their respective sections in
114+
this document. While patches will be accepted into the stable-X.Y branch at
115+
any point in time, significant changes will likely not be accepted into the dev
116+
branch when there are two or less weeks left in the development cycle; this
117+
typically means that only critical bugfixes are accepted once the vX.Y-rc6
118+
kernel is released. During this time the next branch will be regenerated on an
119+
as needed basis based on changes in the component branches, and pull requests
120+
will be sent as needed to Linus for patches in the stable-X.Y branch.
121+
122+
Once Linus releases the final vX.Y kernel and the merge window opens, two
123+
things will happen. The first is that the dev branch will be duplicated into
124+
a new stable-X'.Y' branch, representing the new upcoming kernel release, and
125+
the second is that a pull request will be sent from this branch for inclusion
126+
into the current merge window. During the merge window process the dev and
127+
next branches should be frozen, although there is a possibility that some
128+
patches may be merged into dev-staging for testing or process related reasons.
129+
130+
#### Pull Requests for Linus
131+
132+
In order to send a pull request to Linus, either for a critical bugfix or as
133+
part of the merge window, a signed git tag must be created that points to the
134+
pull request point. The tag should be named using the "{subsystem}-pr-{date}"
135+
format and can be generated with the following git command:
136+
137+
```
138+
% git tag -s -m "{subsystem}/stable-X'.Y' PR {date}" {subsystem}-pr-{date}
139+
```
140+
141+
Once the signed tag has been created, it should be used as the basis for the
142+
pull request.
143+
144+
## Userspace Tools and Test Suites
145+
146+
The audit userspace tools and test suites are hosted by GitHub:
147+
148+
* https://github.com/linux-audit

‎README.orig‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Linux kernel
2+
============
3+
4+
There are several guides for kernel developers and users. These guides can
5+
be rendered in a number of formats, like HTML and PDF. Please read
6+
Documentation/admin-guide/README.rst first.
7+
8+
In order to build the documentation, use ``make htmldocs`` or
9+
``make pdfdocs``. The formatted documentation can also be read online at:
10+
11+
https://www.kernel.org/doc/html/latest/
12+
13+
There are various text files in the Documentation/ subdirectory,
14+
several of them using the Restructured Text markup notation.
15+
16+
Please read the Documentation/process/changes.rst file, as it contains the
17+
requirements for building and running the kernel, and information about
18+
the problems which may result by upgrading your kernel.

‎SECURITY.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Audit Kernel Subsystem Security Policy
2+
=============================================================================
3+
4+
The audit kernel developers take security very seriously and if you think you
5+
have found a serious problem or security vulnerability in the audit kernel
6+
code you are encouraged to send email to the current audit kernel maintainer
7+
who is listed below:
8+
9+
* Paul Moore, [email protected]
10+
11+
## Linux Kernel General Security Policy
12+
13+
In addition to the contact information above, the Linux Kernel also has a
14+
security policy documented in the link below:
15+
16+
* https://github.com/linux-audit/audit-kernel/blob/main/Documentation/admin-guide/security-bugs.rst

0 commit comments

Comments
 (0)