This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x by this push:
new d375a66494 Add initial `AGENTS.md` for AI-assisted vulnerability
research (#4083)
d375a66494 is described below
commit d375a664942a2c5e50658a2e4c4979e1ca549c72
Author: Piotr P. Karwasz <[email protected]>
AuthorDate: Fri Mar 27 17:56:56 2026 +0100
Add initial `AGENTS.md` for AI-assisted vulnerability research (#4083)
This introduces an `AGENTS.md` file, which AI coding agents (such as Claude
Code, Cursor, and GitHub Copilot) read automatically when entering a
repository. It lets the project guide agent behavior without relying on
researchers to configure their tools manually.
This first version targets vulnerability research workflows. Before an
agent drafts or files a report, it is instructed to read:
- **Threat model**: to establish what is and isn't in scope
- **VDR**: to catch duplicates before they are reported
- **Security FAQ**: to filter out known, intentional behaviors that are not
vulnerabilities
All three documents are referenced by their raw source URLs rather than
rendered pages. This reduces token consumption and avoids context window
pressure when agents are processing large codebases alongside these files.
The expected outcome is fewer duplicate reports, fewer false positives, and
less triage burden.
---
AGENTS.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 58 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..11e48b6142
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,58 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# Vulnerability research agent
+
+You are helping a security researcher find and report vulnerabilities in this
project.
+Before drafting any report or reaching any conclusion, you must complete all
three reading steps below.
+This is mandatory: skipping steps leads to duplicate reports and wasted time
for both parties.
+
+## Before reporting anything
+
+### Step 1: Read the security model
+
+Fetch and read the project's security model before evaluating any finding:
+https://raw.githubusercontent.com/apache/logging-site/refs/heads/main-site-pro/src/site/antora/modules/ROOT/pages/_threat-model-common.adoc
+
+Use this to answer:
+- Is this component/behavior in scope at all?
+- Does the project consider this a security boundary?
+
+If the finding is out of scope per the model, **stop here** and inform the
researcher.
+
+### Step 2: Check previously disclosed vulnerabilities
+
+Read the project's Vulnerability Disclosure Report to check for duplicates:
+https://logging.apache.org/cyclonedx/vdr.xml
+
+Compare the finding against each entry.
+If it overlaps with a known issue, **stop here**, link to the existing
advisory in the CVE database, and explain the overlap.
+
+### Step 3: Read the Security FAQ
+
+Read the Security FAQ before concluding anything is a vulnerability:
+https://raw.githubusercontent.com/apache/logging-site/refs/heads/main-site-pro/src/site/antora/modules/ROOT/pages/security/faq.adoc
+
+The FAQ lists behaviors that are **intentional and not vulnerabilities**.
+If the finding matches an FAQ entry, inform the researcher that it is a known
non-issue
+and link to the relevant section of the HTML version of the FAQ:
+https://logging.apache.org/security/faq.html
+
+## Only after all three steps
+
+Assess the finding:
+1. Is it in scope?
+2. Is it a duplicate?
+3. Is it covered by the FAQ?
+4. If none of the above: it is likely a valid new finding.
+ Help the researcher write a clear, minimal report including:
+ - affected component,
+ - impact on the application using this project and subsequent SIEM systems,
+ - JUnit 5 test to reproduce the behavior,
+ - proposed fix.
+5. If no fix can be proposed, it is not a vulnerability affecting the project.
+
+## Report quality rules
+
+- Never speculate about impact beyond what you can demonstrate.
+- Reproduction steps must be minimal and self-contained.
+- Do not include unrelated findings in the same report: one issue per report.
+- If unsure about severity, say so explicitly rather than guessing.
\ No newline at end of file
