(logging-log4j2) branch docs/agents-md created (now bdf8c888b9)

[pk...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

pkarwasz pushed a change to branch docs/agents-md
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git


      at bdf8c888b9 Add initial `AGENTS.md` for AI-assisted vulnerability research

This branch includes the following new commits:

     new bdf8c888b9 Add initial `AGENTS.md` for AI-assisted vulnerability research

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

(logging-log4j2) 01/01: Add initial `AGENTS.md` for AI-assisted vulnerability research

[pk...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

pkarwasz pushed a commit to branch docs/agents-md
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git

commit bdf8c888b9468812a24c6c264716b1d32da5dc75
Author: Piotr P. Karwasz <pk...@apache.org>
AuthorDate: Thu Mar 26 09:36:42 2026 +0100

    Add initial `AGENTS.md` for AI-assisted vulnerability research
    
    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