From f5e985fcd1cb95a08df5f84f763189db2082af40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felipe=20Say=C3=A3o=20Lobato=20Abreu?= Date: Sat, 17 Oct 2026 17:09:52 -0300 Subject: [PATCH] docs: define security support and private reporting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document latest-stable security support and the existing private channel. Ship SECURITY.md in Composer archives and verify its required presence. Link the policy from consumer and contributor entrypoints. Signed-off-by: Felipe Sayão Lobato Abreu --- .changeset/security-reporting-policy.md | 5 ++++ AGENTS.md | 1 + README.md | 3 +++ SECURITY.md | 27 +++++++++++++++++++ resources/skills/coisa-error-handler/SKILL.md | 4 +++ tests/Functional/ConsumerSkillArchiveTest.php | 14 +++++++++- tests/Production/archive.php | 4 +-- 7 files changed, 55 insertions(+), 3 deletions(-) create mode 100644 .changeset/security-reporting-policy.md create mode 100644 SECURITY.md diff --git a/.changeset/security-reporting-policy.md b/.changeset/security-reporting-policy.md new file mode 100644 index 0000000..22130dc --- /dev/null +++ b/.changeset/security-reporting-policy.md @@ -0,0 +1,5 @@ +--- +"@coisa/error-handler": patch +--- + +Document security support for the latest stable release and the existing private reporting channel. Include the security policy in Composer distributions and link it from the README and consumer skill. diff --git a/AGENTS.md b/AGENTS.md index 0d5023c..154359c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,6 +38,7 @@ and verification continue to follow this AGENTS.md. ## Child DOX Index +- [SECURITY.md](SECURITY.md): latest-stable security support and private vulnerability reporting; ordinary bugs remain public issues. - [README.md](README.md): consumer installation, quick start and guide navigation; distinguishes API family from pending release state. - [docs/api.md](docs/api.md): reporters, core lifecycle and process behavior; no recovery or exit guarantees. - [docs/container.md](docs/container.md): legacy container, ConfigProvider, factories and cached scopes; applications supply external implementations. diff --git a/README.md b/README.md index 6404266..218dfaa 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,9 @@ status-code mapping, reason validation and output-buffer cleanup limits. ## 🤝 Contributing +For suspected vulnerabilities, follow the [security policy](SECURITY.md) and use +the private reporting channel. Ordinary bugs and feature requests belong in issues. + Follow the [contributor guide](CONTRIBUTING.md) for dependency setup and `composer --no-plugins check`. See [testing](docs/testing.md) for process fixtures and platform evidence, and [Changesets](.changeset/README.md) for release notes. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..96b9878 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,27 @@ +# Security policy + +## Supported releases + +Security fixes are provided for the latest stable release of `coisa/error-handler`. +Reports concerning older releases are welcome; upgrade to the latest stable +release to receive fixes. + +## Report a vulnerability privately + +Use the repository's [private vulnerability reporting channel](https://github.com/coisa/error-handler/security/advisories/new). +Keep suspected vulnerabilities out of public issues until disclosure has been coordinated. + +Include: + +- The affected package version, PHP version and relevant optional dependencies. +- The impact, required configuration and conditions needed to reproduce it. +- A minimal synthetic reproduction, with expected and observed behavior. +- Any workaround or mitigation you have already verified. + +Do not send credentials, tokens, customer data or production logs. Replace real +application records with synthetic examples. + +## Ordinary bugs and feature requests + +Use [repository issues](https://github.com/coisa/error-handler/issues) for bugs +without a security impact and for feature proposals. diff --git a/resources/skills/coisa-error-handler/SKILL.md b/resources/skills/coisa-error-handler/SKILL.md index 359d1ba..540c7c9 100644 --- a/resources/skills/coisa-error-handler/SKILL.md +++ b/resources/skills/coisa-error-handler/SKILL.md @@ -148,3 +148,7 @@ executed checks and concrete limits. Shipping files, copying the package, discovery after a session refresh and successful agent use are separate results. This procedure does not authorize deployment, publication, global installation or production diagnostics. + +For suspected security issues, follow the source repository's +[security policy](https://github.com/coisa/error-handler/security/policy) and use +its private reporting channel. Use ordinary issues for non-security bugs and features. diff --git a/tests/Functional/ConsumerSkillArchiveTest.php b/tests/Functional/ConsumerSkillArchiveTest.php index 33c7fed..460691d 100644 --- a/tests/Functional/ConsumerSkillArchiveTest.php +++ b/tests/Functional/ConsumerSkillArchiveTest.php @@ -85,6 +85,18 @@ public function testMissingBundledExampleIsRejected(): void $this->verifyArchive(); } + /** + * Composer packages must retain the policy that identifies confidential reporting. + */ + public function testMissingSecurityPolicyIsRejected(): void + { + $this->createArchive('SECURITY.md'); + $this->expectException(\RuntimeException::class); + $this->expectExceptionMessage('Required runtime or consumer metadata is missing: SECURITY.md'); + + $this->verifyArchive(); + } + /** * Packaging cannot silently substitute different consumer instructions. */ @@ -125,7 +137,7 @@ public function testOtherResourceDirectoriesRemainForbidden(): void private function createArchive(?string $omittedPath = null): \PharData { $root = \dirname(__DIR__, 2); - $paths = ['composer.json', 'LICENSE', 'README.md', 'CHANGELOG.md']; + $paths = ['composer.json', 'LICENSE', 'README.md', 'CHANGELOG.md', 'SECURITY.md']; foreach (['src', 'resources/skills/coisa-error-handler'] as $directory) { $sourceFiles = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($root . '/' . $directory)); diff --git a/tests/Production/archive.php b/tests/Production/archive.php index 3809b6c..c8e5eab 100644 --- a/tests/Production/archive.php +++ b/tests/Production/archive.php @@ -38,7 +38,7 @@ $path = substr($file->getPathname(), strlen($prefix)); // Runtime code, useful guides and the canonical consumer skill are distribution assets. - $allowed = in_array($path, ['composer.json', 'LICENSE', 'README.md', 'CHANGELOG.md'], true) + $allowed = in_array($path, ['composer.json', 'LICENSE', 'README.md', 'CHANGELOG.md', 'SECURITY.md'], true) || 0 === strpos($path, 'src/') || 0 === strpos($path, 'docs/') || 0 === strpos($path, 'resources/skills/coisa-error-handler/'); @@ -54,7 +54,7 @@ $files[$path] = true; } -$required = ['composer.json', 'LICENSE', 'README.md', 'CHANGELOG.md']; +$required = ['composer.json', 'LICENSE', 'README.md', 'CHANGELOG.md', 'SECURITY.md']; foreach (['src', 'resources/skills/coisa-error-handler'] as $directory) { /** @var SplFileInfo $source A required runtime or consumer skill file from the selected source. */