diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6f966a18..c7d649c6 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -21,12 +21,8 @@ Thanks for submitting a pull request, please make sure: - [ ] content meets the [license](https://github.com/OWASP/DevGuide/blob/main/license.txt) for this project - [ ] you have read the [contribution guide](https://github.com/OWASP/DevGuide/blob/main/contributing.md) and agree to the [Code of Conduct](https://github.com/OWASP/DevGuide/blob/main/code_of_conduct.md) -- [ ] *either* no AI-generated content has been used in this pull request -- [ ] *or* any [use of AI](https://github.com/OWASP/DevGuide/blob/main/contributing.md#use-of-ai) - in this pull request has been disclosed below: - - AI Tools: `[e.g. GitHub CoPilot, ChatGPT, JetBrains Junie, etc]` - - LLMs and versions: `[e.g. GPT-4.1, Claude Haiku 4.5, Gemini 2.5 Pro, etc]` - - Prompts: `[Summarize the key prompts or instructions given to the AI tools]` +- [ ] no agentic AI was used in creating this pull request +- [ ] no generative AI was used in creating content under `/docs` **Other info** : diff --git a/.wordlist-en.txt b/.wordlist-en.txt index 766c5e1a..3f07ed02 100644 --- a/.wordlist-en.txt +++ b/.wordlist-en.txt @@ -265,6 +265,7 @@ SDLCs SECCOMP SELinux SFL +SHA SIEM SKF SL @@ -489,6 +490,7 @@ lxml lychee mastg maswe +md misconfiguration mlsec mitigations diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..3b14932f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,67 @@ +# AGENTS.md + +This is the repo-level operating contract for agents working in OWASP Developer Guide. +***These rules are requirements, not suggestions.*** + +## Project Goals + +The OWASP Developer Guide is a free, open-source OWASP threat modeling tool. +It is a documentation project that provides software developers and development teams with insights into software security. + +## Operating Contracts + +### Agents + +This is the repo-level operating contract for non-human OWASP Developer Guide contributors. +These rules are requirements, ***not suggestions***. + +### Contributing + +The [contributing.md](./contributing.md) file is the operating contract for our human contributors. +Non-human contributors must read, understand, and respect these contracts. + +### Code of Conduct + +The [code_of_conduct.md](./code_of_conduct.md) applies to all contributors - +regardless of whether the contributor is carbon-based, silicon-based, or legally ambiguous. + +## Explicit Boundaries + +1. Humans are responsible for all contributions, regardless of tooling. +2. AI should explicitly refuse to take action clearly prohibited by this AGENTS file +3. Humans write public product docs under `docs/`. Agents must not author docs pages +4. Humans create issues, comment on issues, submit pull requests, approve releases, publish artifacts +5. Humans decide roadmap or product policy +6. Agents may point out docs gaps, but a human must write the final docs text. +7. Agents may test docs with markdown linting, spellcheck, link checks, and local docs builds +8. Agents may edit code, tests, configuration, workflows, and maintainer scripts when explicitly asked +9. Agents must not open issues, comment on GitHub, open pull requests, approve pull requests +10. Agents must not commit, merge, push, release, or publish +11. Do not mix unrelated cleanup, dependency updates, formatting churn, or opportunistic refactors into task work + +## Supply Chain / Dependencies + +- ALL dependencies must have a minimum release age of 10 days +- No updates to lock-files unless intentionally doing dependency work +- GitHub Actions must be pinned to a full commit SHA with an inline version comment for Dependabot +- GitHub Actions have the same 10 day minimum release age requirement +- Prefer small helper scripts over new dependencies when reasonable + +### docs + +- Docs checks are for validation only: markdown lint, spellcheck, link check, and docs build where available + +### Root level checks + +- `npm run markdown:lint` +- Spellcheck is not available as an npm command. You can run it if: + - the user has or approves installing pyspelling + - the `en` dictionary is installed + - `pyspelling -c .spellcheck.yaml` + +## Directory Specific Context + +### `docs/` + +- Agents do not write public documentation pages. +- Agents may validate human-authored docs with markdown formatting, spellcheck, link checks, and local docs builds. diff --git a/contributing.md b/contributing.md index c5466d5c..4eb3a232 100644 --- a/contributing.md +++ b/contributing.md @@ -14,8 +14,20 @@ Contributors can [make suggestions][issues] and provide changes via a [pull requ Feel free to discuss topics in the [project wiki][wiki] and create new discussions. +### Generative AI + Note that you **must** follow the rules for any [use of AI](#use-of-ai). +The use of AI is quick and seems to provide what is needed +but ultimately it does not deliver true insight into what projects actually are, +why a developer would want to use them and how they need to be used; +it can only provide superficial answers + +This Developer Guide seeks to provide knowledge about the various OWASP projects. +This requires human insight that provides a developer with reasons and knowledge that go beyond what can be gleaned by AI. +Perhaps it is the difference between a Lonely Planet Guide and Google Maps; +one has human insight and the other is truthful but mechanical + ### Ground rules When contributing: @@ -25,16 +37,19 @@ When contributing: * ensure that all contributions are within the [license](license.txt) * although the use of generative AI is not prohibited, it _must_ be declared in the pull request -The Developer Guide is a documentation project and so there may be differences of opinion on wording or punctuation. -If you submit a pull request please make it substantive, otherwise +When you submit a pull request please make it substantive, otherwise it will be hard to get attention from the maintainers for trivial changes and it may end up being rejected. +The Developer Guide is a documentation project and so there may be differences of opinion on wording or punctuation. + #### Philosophy The Developer Guide does not seek to duplicate the information contained in the many OWASP documentation projects; these projects address their subject fully and completely. + Instead the Developer Guide is a starting point on a wide range of subjects which a developer would need to know at least the basics. + The Developer Guide should supply this basic knowledge only, and then refer the developer to further reading for more in-depth treatment of the subject. As a rule of thumb, if a section is more than two pages then it is probably too long; @@ -83,12 +98,12 @@ Sub-sections that describe an individual project should follow the same structur 3. The 'Why', explaining why developers will want to use the project: _provide more context for project that allows developers to determine whether to use it in their team_ 4. The 'How', describe how to get started with the project - _give a brief outline of how the project provides value for a web application development team_ + _give a brief outline of how the project provides value for a web application development team_. _Do not repeat the project documentation itself; ideally provide a primer and a pointer to the project documentation_ 5. Further reading or resources, if any, providing links on the project at an advanced/detailed level Note that the page describing a project should not be the same as the project documentation on the OWASP site, -the Developer Guide should strive to be a ' TL;DR ' for the project running to one or maybe two pages. +the Developer Guide should strive to be a ' TL;DR ' for the project in one or maybe two pages. ### Translations @@ -122,14 +137,12 @@ Note that you **must** follow the rules for any [use of AI](#use-of-ai) in the p ### Use of AI The Developer Guide is a documentation project and so the content must be accurate, informative and concise. +Generative AI usually produces content that is superficial, generalized and verbose; **do not** use it to create content. -Generative AI can produce content that is general and verbose; -avoid using it for any issues, pull requests, comments and discussions. - -If it is genuinely helpful to use generative AI then it **must** be declared in any pull request or issue, -failure to do so can result in the contribution being closed or even deleted. +**Do not** use generative AI for any issues, pull requests, comments and discussions. +Use of generative AI will result in the contribution being closed or even deleted. -There is no need to use agentic AI to create issues or pull requests; +**Do not** use agentic AI to create issues or pull requests; templates for all issues and pull requests **must** be used. Failure to use the templates can result in the issue / pull request being closed or even deleted.