Skip to content

Commit 8aed2ef

Browse files
pcmoorepcmoore
committed
audit: add a Linux Audit specific README.md and SECURITY.md
DO NOT SUBMIT UPSTREAM
1 parent 05f7e89 commit 8aed2ef

4 files changed

Lines changed: 192 additions & 153 deletions

File tree

‎README‎

Lines changed: 10 additions & 153 deletions
Original file line numberDiff line numberDiff line change
@@ -1,156 +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-
The Linux kernel is the core of any Linux operating system. It manages hardware,
5-
system resources, and provides the fundamental services for all other software.
6+
The original Linux Kernel README file:
7+
* https://github.com/linux-audit/audit-kernel/blob/main/README.orig
68

7-
Quick Start
8-
-----------
9+
The Linux Kernel audit subsystem README.md file:
10+
* https://github.com/linux-audit/audit-kernel/blob/main/README.md
911

10-
* Report a bug: See Documentation/admin-guide/reporting-issues.rst
11-
* Get the latest kernel: https://kernel.org
12-
* Build the kernel: See Documentation/admin-guide/quickly-build-trimmed-linux.rst
13-
* Join the community: https://lore.kernel.org/
14-
15-
Essential Documentation
16-
-----------------------
17-
18-
All users should be familiar with:
19-
20-
* Building requirements: Documentation/process/changes.rst
21-
* Code of Conduct: Documentation/process/code-of-conduct.rst
22-
* License: See COPYING
23-
24-
Documentation can be built with make htmldocs or viewed online at:
25-
https://www.kernel.org/doc/html/latest/
26-
27-
28-
Who Are You?
29-
============
30-
31-
Find your role below:
32-
33-
* New Kernel Developer - Getting started with kernel development
34-
* Academic Researcher - Studying kernel internals and architecture
35-
* Security Expert - Hardening and vulnerability analysis
36-
* Backport/Maintenance Engineer - Maintaining stable kernels
37-
* System Administrator - Configuring and troubleshooting
38-
* Maintainer - Leading subsystems and reviewing patches
39-
* Hardware Vendor - Writing drivers for new hardware
40-
* Distribution Maintainer - Packaging kernels for distros
41-
42-
43-
For Specific Users
44-
==================
45-
46-
New Kernel Developer
47-
--------------------
48-
49-
Welcome! Start your kernel development journey here:
50-
51-
* Getting Started: Documentation/process/development-process.rst
52-
* Your First Patch: Documentation/process/submitting-patches.rst
53-
* Coding Style: Documentation/process/coding-style.rst
54-
* Build System: Documentation/kbuild/index.rst
55-
* Development Tools: Documentation/dev-tools/index.rst
56-
* Kernel Hacking Guide: Documentation/kernel-hacking/hacking.rst
57-
* Core APIs: Documentation/core-api/index.rst
58-
59-
Academic Researcher
60-
-------------------
61-
62-
Explore the kernel's architecture and internals:
63-
64-
* Researcher Guidelines: Documentation/process/researcher-guidelines.rst
65-
* Memory Management: Documentation/mm/index.rst
66-
* Scheduler: Documentation/scheduler/index.rst
67-
* Networking Stack: Documentation/networking/index.rst
68-
* Filesystems: Documentation/filesystems/index.rst
69-
* RCU (Read-Copy Update): Documentation/RCU/index.rst
70-
* Locking Primitives: Documentation/locking/index.rst
71-
* Power Management: Documentation/power/index.rst
72-
73-
Security Expert
74-
---------------
75-
76-
Security documentation and hardening guides:
77-
78-
* Security Documentation: Documentation/security/index.rst
79-
* LSM Development: Documentation/security/lsm-development.rst
80-
* Self Protection: Documentation/security/self-protection.rst
81-
* Reporting Vulnerabilities: Documentation/process/security-bugs.rst
82-
* CVE Procedures: Documentation/process/cve.rst
83-
* Embargoed Hardware Issues: Documentation/process/embargoed-hardware-issues.rst
84-
* Security Features: Documentation/userspace-api/seccomp_filter.rst
85-
86-
Backport/Maintenance Engineer
87-
-----------------------------
88-
89-
Maintain and stabilize kernel versions:
90-
91-
* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst
92-
* Backporting Guide: Documentation/process/backporting.rst
93-
* Applying Patches: Documentation/process/applying-patches.rst
94-
* Subsystem Profile: Documentation/maintainer/maintainer-entry-profile.rst
95-
* Git for Maintainers: Documentation/maintainer/configure-git.rst
96-
97-
System Administrator
98-
--------------------
99-
100-
Configure, tune, and troubleshoot Linux systems:
101-
102-
* Admin Guide: Documentation/admin-guide/index.rst
103-
* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst
104-
* Sysctl Tuning: Documentation/admin-guide/sysctl/index.rst
105-
* Tracing/Debugging: Documentation/trace/index.rst
106-
* Performance Security: Documentation/admin-guide/perf-security.rst
107-
* Hardware Monitoring: Documentation/hwmon/index.rst
108-
109-
Maintainer
110-
----------
111-
112-
Lead kernel subsystems and manage contributions:
113-
114-
* Maintainer Handbook: Documentation/maintainer/index.rst
115-
* Pull Requests: Documentation/maintainer/pull-requests.rst
116-
* Managing Patches: Documentation/maintainer/modifying-patches.rst
117-
* Rebasing and Merging: Documentation/maintainer/rebasing-and-merging.rst
118-
* Development Process: Documentation/process/maintainer-handbooks.rst
119-
* Maintainer Entry Profile: Documentation/maintainer/maintainer-entry-profile.rst
120-
* Git Configuration: Documentation/maintainer/configure-git.rst
121-
122-
Hardware Vendor
123-
---------------
124-
125-
Write drivers and support new hardware:
126-
127-
* Driver API Guide: Documentation/driver-api/index.rst
128-
* Driver Model: Documentation/driver-api/driver-model/driver.rst
129-
* Device Drivers: Documentation/driver-api/infrastructure.rst
130-
* Bus Types: Documentation/driver-api/driver-model/bus.rst
131-
* Device Tree Bindings: Documentation/devicetree/bindings/
132-
* Power Management: Documentation/driver-api/pm/index.rst
133-
* DMA API: Documentation/core-api/dma-api.rst
134-
135-
Distribution Maintainer
136-
-----------------------
137-
138-
Package and distribute the kernel:
139-
140-
* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst
141-
* ABI Documentation: Documentation/ABI/README
142-
* Kernel Configuration: Documentation/kbuild/kconfig.rst
143-
* Module Signing: Documentation/admin-guide/module-signing.rst
144-
* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst
145-
* Tainted Kernels: Documentation/admin-guide/tainted-kernels.rst
146-
147-
148-
149-
Communication and Support
150-
=========================
151-
152-
* Mailing Lists: https://lore.kernel.org/
153-
* IRC: #kernelnewbies on irc.oftc.net
154-
* Bugzilla: https://bugzilla.kernel.org/
155-
* MAINTAINERS file: Lists subsystem maintainers and mailing lists
156-
* Email Clients: Documentation/process/email-clients.rst
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, paul@paul-moore.com
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)