From e2eb1bbac249813e952b4fdd67f46c536f8a966d Mon Sep 17 00:00:00 2001 From: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com> Date: Tue, 17 Nov 2026 11:01:43 +0000 Subject: [PATCH 01/11] Add the issue-priority skill for the Priority issue field The skill gives the rules for the org issue field Priority (Urgent, High, Medium, Low) on clickhouse-cpp issues: reach tiers of the library, severity, the base-level matrix, modifiers, and confidence. People and automated triage use the same rules. AGENTS.md points to it. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/issue-priority/SKILL.md | 132 +++++++++++++++++++++++++ AGENTS.md | 4 + 2 files changed, 136 insertions(+) create mode 100644 .claude/skills/issue-priority/SKILL.md diff --git a/.claude/skills/issue-priority/SKILL.md b/.claude/skills/issue-priority/SKILL.md new file mode 100644 index 00000000..ecae1338 --- /dev/null +++ b/.claude/skills/issue-priority/SKILL.md @@ -0,0 +1,132 @@ +--- +name: issue-priority +description: > + Decide the priority of a `ClickHouse/clickhouse-cpp` issue: `Urgent`, `High`, + `Medium`, or `Low`, for the org issue field **Priority**. Use this skill when + the task is to "prioritize", "set the priority of", "rate", or "triage" an + issue, or to explain why an issue has a given priority. It defines the reach + tiers of the library, the severity rows, the base-level matrix, the + modifiers, and the confidence. +--- + +# Issue priority + +This skill is the single source of truth for the **Priority** of +`ClickHouse/clickhouse-cpp` issues. People and automated triage use the same +rules. + +The value goes into the org issue field **Priority** (`Urgent`, `High`, +`Medium`, `Low`). The field is visible to org members only. An automated tool +sets the value once, never changes a value that is already set, and keeps the +level and its reason out of public comments. + +## When to set no priority + +Set no priority when one of these is true: + +- A maintainer can close the issue with no further action: it is already fixed + on `master`, a duplicate, works as intended, already supported, answered, or + obsolete. "Works as intended" includes a failure that shows only when two + threads use one `Client` (README, "Thread-safety"). +- Only a deprecated public API reaches the defect: a `[[deprecated]]` + attribute, a header that prints a deprecation `#warning` (for example + `clickhouse/columns/utils.h`), or docs that call the API deprecated. Fixes to + deprecated code are not released. One exception: the Abseil-backed + `Int128`/`UInt128` (`CH_ABSEIL_BIGNUM_DEPRECATED`) is deprecated, but it is + the default of the 2.x build (`CH_USE_ABSEIL_FOR_BIGNUM=ON`). Rate its + defects normally (section 1). +- The issue is a question, or it is about CI, the release process, or a + discussion. + +## 1. Reach + +The reach is the tier of the most-used public path that reaches the defect, +not the tier of the file that contains it. Every `Select()` parses the column +types that the server sends (`clickhouse/types/type_parser.cpp`) and creates +the columns (`clickhouse/columns/factory.cpp`). So a parser defect for a common +type is Core, and a parser defect that only an unusual type name reaches is +Narrow. + +| Tier | Public paths | +| --------- | ------------ | +| Core | `Client` connect, handshake, and authentication; `Execute()`, `Select()`, `Insert()`, `Ping()`, `ResetConnection()`; endpoint failover (`SetEndpoints`); timeouts and keep-alive in `ClientOptions`; TLS (`SetSSLOptions`, `WITH_OPENSSL`; ClickHouse Cloud needs it); error handling (`ServerException`, `ProtocolError`, and the connection state after an error); `Block` and the Native codec for `(U)Int8`–`(U)Int64`, `Float32`, `Float64`, `String`, `FixedString`, `Date`, `DateTime`, `DateTime64`, `Decimal32`–`Decimal128`, `UUID`, `Nullable(T)`, `Array(T)`, and `LowCardinality(String)`; the CMake build with the default options on a platform and compiler that CI tests | +| Common | compression (`SetCompressionMethod`: LZ4, ZSTD); multi-block insert (`BeginInsert`, `SendInsertBlock`, `EndInsert`); streaming and cancelable select (`BeginSelect`, `NextBlock`, `SelectCancelable`, `Cancel`); query settings and parameters (`Query::SetSetting`, `SetParam`); `Query` callbacks (progress, profile, server log, profile events, exception); external data (`SelectWithExternalData`); the types `Bool`, `Enum8`, `Enum16`, `Map`, `Tuple`, `IPv4`, `IPv6`, `Int128`, `UInt128`, and the other `LowCardinality` and nested wrappers; column methods (`Append`, `Slice`, `Reserve`, `Clear`, `Swap`, `GetItem`); the build with Bazel, MinGW, shared libraries, system dependencies (`WITH_SYSTEM_*`), `CH_USE_3X_API` and its options, and the `make install` layout | +| Narrow | rare types (`Point`, `Ring`, `Polygon`, `MultiPolygon`, `JSON`, `Time`, `Time64`, `Nothing`, `Nested`); unusual type names (escaped `Enum` labels, deep nesting); input that a correct server does not send (a malformed packet or type name); caller input that the type or the API does not allow, but that the library does not reject (an undeclared `Enum` value, a column of the wrong type); OpenTelemetry tracing context; a compiler, platform, or dependency version that CI does not test | +| Satellite | `examples/`, `bench/`, `ut/`, `tests/`, `docs/`, `README.md`; packages that other projects maintain (Conan Center, vcpkg, Homebrew, distribution packages) | + +The 2.x build uses the Abseil-backed `Int128`/`UInt128` by default. A defect +that only this implementation has is Common (`Int128`, `UInt128`). If the +self-contained implementation does not have the defect, the workaround is the +build flag `-DCH_USE_ABSEIL_FOR_BIGNUM=OFF` (severity "Workaround exists"). + +## 2. Severity + +Use the first row that fits: + +| Severity | Use when | +| ----------------------- | -------- | +| Wrong data or security | the client returns or stores wrong or incomplete data with no error (this includes a block stream that goes out of sync with no error), or reports success for a query that failed; or a security defect: a leak of credentials or data, a TLS verification that does not occur, SQL built from a caller value without escaping, or memory corruption (an out-of-bounds write, a use after free). A hang or a crash that only a hostile server or network causes is not a security defect: rate it by the failure | +| Broken, no workaround | the feature fails (an exception, a hang, a crash, an abort, a leak that ends in a crash or in exhausted sockets), and the caller has no reasonable workaround; also a `Client` that stays unusable after an error, and a build that fails on a supported toolchain; also a wrong or incomplete error with no workaround: the failure is reported, but its type, code, or message is wrong or lost | +| Workaround exists | the feature fails, but the caller can avoid the failure with a small change in their own code or build flags (name the workaround in the reason); also a result that is correct but slow or uses too much memory | +| Cosmetic, docs, feature | wrong log or message text, a compiler warning, documentation, a feature request (this includes support for a new type or a new package manager) | + +## 3. Base level + +| Severity ↓ / Reach → | Core | Common | Narrow | Satellite | +| ----------------------- | ------ | ------ | ------ | --------- | +| Wrong data or security | Urgent | Urgent | High | Medium | +| Broken, no workaround | High | High | Medium | Low | +| Workaround exists | Medium | Medium | Low | Low | +| Cosmetic, docs, feature | Low | Low | Low | Low | + +## 4. Modifiers + +Apply them in this order: + +1. **Security with a shown path from untrusted input.** The issue or a + reproduction shows how a value that an application takes from its users + reaches the defect: `Urgent` at any reach. Skip the other modifiers. A + defect that puts a caller-supplied value into SQL without quoting or + escaping is a candidate (for example a table name, a setting, or a query + parameter): look for such a path. If none is shown, rate the defect by the + failure that it shows. A report that discloses a vulnerability goes to a + private channel, not to a public issue. +2. **Regression in the latest published release**: up one level. This can give + `Urgent`. It is a regression only when the latest release shows the problem + and the release before it does not. The tags are `vX.Y.Z` (for example + `v2.6.2` and `v2.6.1`). A defect that only `master` has (after the latest + tag) is not a release regression: no modifier, but write "unreleased + regression" in the reason, so that it is fixed before the next release. +3. **Customer request in Linear.** The issue links (`linear.app`) a Linear + issue for a customer request: up one level, but never to `Urgent` (`High` + stays `High`). + +## 5. Confidence + +A missing reproduction lowers the confidence, not the level. Record the +confidence with the value when the tool that sets it supports it: + +| Confidence | Use when | +| ---------- | -------- | +| `HIGH` | a run shows the problem (or, for a feature, code inspection confirms its absence on `master`) | +| `MEDIUM` | code inspection shows a defect, but no reproduction was run (for example, it needs ClickHouse Cloud or a specific platform) | +| `LOW` | the report lacks what a reproduction needs, or a run did not show the problem | + +## 6. Reason + +Write one line with the value: + +` () · · → .` + +Name the workaround when the severity is "Workaround exists". When the +confidence is `LOW`, say what is missing. + +## 7. Labels from earlier triage + +- `priority-high` and `priority-low` are older labels that a maintainer set. + When an issue has one, use its level (`High` or `Low`) instead of the table + value, and write "maintainer label `priority-…`" in the reason. Never add + these labels. +- `pg_clickhouse` marks a request from the pg_clickhouse PostgreSQL extension. + pg_clickhouse uses clickhouse-c instead of clickhouse-cpp from its v0.3.1 + release, so the label gives no modifier. diff --git a/AGENTS.md b/AGENTS.md index 9fe0f2f9..4f6fc634 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,7 @@ # Communication style - Follow ASD-STE100 + +# When triaging issues + +- To set, check, or explain the Priority of an issue, follow [`.claude/skills/issue-priority/SKILL.md`](.claude/skills/issue-priority/SKILL.md). It is the single source of truth for the priority rules. From acfb7f714d2b39bb75115da19a327f3edab9045d Mon Sep 17 00:00:00 2001 From: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:58:13 +0000 Subject: [PATCH 02/11] Name the impact classes in the issue-priority skill The severity section now starts with four impact classes: Security, Data integrity, Stability, and Performance. They are the same in every ClickHouse client repository. Each severity row names the impact that puts an issue in the row, and the reason line records the impacts. No priority level changes: each row keeps its conditions. Co-Authored-By: Claude Fable 5.2 --- .claude/skills/issue-priority/SKILL.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/.claude/skills/issue-priority/SKILL.md b/.claude/skills/issue-priority/SKILL.md index ecae1338..ba676e1a 100644 --- a/.claude/skills/issue-priority/SKILL.md +++ b/.claude/skills/issue-priority/SKILL.md @@ -5,7 +5,7 @@ description: > `Medium`, or `Low`, for the org issue field **Priority**. Use this skill when the task is to "prioritize", "set the priority of", "rate", or "triage" an issue, or to explain why an issue has a given priority. It defines the reach - tiers of the library, the severity rows, the base-level matrix, the + tiers of the library, the impact classes, the severity rows, the base-level matrix, the modifiers, and the confidence. --- @@ -61,13 +61,27 @@ build flag `-DCH_USE_ABSEIL_FOR_BIGNUM=OFF` (severity "Workaround exists"). ## 2. Severity -Use the first row that fits: +First name the **impacts** of the issue. The impact classes are the same in +every ClickHouse client repository. An issue has none, one, or more of them: + +| Impact | Use when | +| -------------- | -------- | +| Security | a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query, skips or weakens a TLS or identity check, or lets a remote party stop the client; also an authentication method that does not work or is missing | +| Data integrity | data that the caller wrote, or a result that the caller reads, is missing, incomplete, or different from the value given or stored, and the client reports no error; this includes a failed operation that the client reports as a success | +| Stability | the process stops in a way that the caller cannot handle as a normal error, a call does not return, or a resource leaks until none is left | +| Performance | the result is correct, but the operation is too slow, or uses too much memory or CPU | + +Give an impact only when the issue or a reproduction shows it. Most issues have +none. + +Then use the first severity row that fits. With more than one impact, the +highest row applies: | Severity | Use when | | ----------------------- | -------- | -| Wrong data or security | the client returns or stores wrong or incomplete data with no error (this includes a block stream that goes out of sync with no error), or reports success for a query that failed; or a security defect: a leak of credentials or data, a TLS verification that does not occur, SQL built from a caller value without escaping, or memory corruption (an out-of-bounds write, a use after free). A hang or a crash that only a hostile server or network causes is not a security defect: rate it by the failure | -| Broken, no workaround | the feature fails (an exception, a hang, a crash, an abort, a leak that ends in a crash or in exhausted sockets), and the caller has no reasonable workaround; also a `Client` that stays unusable after an error, and a build that fails on a supported toolchain; also a wrong or incomplete error with no workaround: the failure is reported, but its type, code, or message is wrong or lost | -| Workaround exists | the feature fails, but the caller can avoid the failure with a small change in their own code or build flags (name the workaround in the reason); also a result that is correct but slow or uses too much memory | +| Wrong data or security | impact **Data integrity**: the client returns or stores wrong or incomplete data with no error (this includes a block stream that goes out of sync with no error), or reports success for a query that failed; or impact **Security**: a security defect: a leak of credentials or data, a TLS verification that does not occur, SQL built from a caller value without escaping, or memory corruption (an out-of-bounds write, a use after free). A hang or a crash that only a hostile server or network causes does not use this row: rate it by the failure. A request for an authentication method is a feature request | +| Broken, no workaround | the feature fails (an exception, a hang, a crash, an abort, a leak that ends in a crash or in exhausted sockets), and the caller has no reasonable workaround; also a `Client` that stays unusable after an error, and a build that fails on a supported toolchain; also a wrong or incomplete error with no workaround: the failure is reported, but its type, code, or message is wrong or lost. The impact **Stability** (a hang, a crash, such a leak) uses this row when the caller has no reasonable workaround | +| Workaround exists | the feature fails, but the caller can avoid the failure with a small change in their own code or build flags (name the workaround in the reason); also impact **Performance**: a result that is correct but slow or uses too much memory | | Cosmetic, docs, feature | wrong log or message text, a compiler warning, documentation, a feature request (this includes support for a new type or a new package manager) | ## 3. Base level @@ -116,7 +130,7 @@ confidence with the value when the tool that sets it supports it: Write one line with the value: -` () · · → .` +` () · · · → .` Name the workaround when the severity is "Workaround exists". When the confidence is `LOW`, say what is missing. From 55aca8fb2070c830c1deea54f4dd55acb94c87df Mon Sep 17 00:00:00 2001 From: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com> Date: Wed, 18 Nov 2026 06:29:21 +0000 Subject: [PATCH 03/11] Separate vulnerabilities from authentication in the issue-priority skill The impact Security has two parts: a vulnerability, and authentication. Only a vulnerability uses the row "Wrong data or security". An authentication method that does not work is rated by its failure, and a request for a missing method is a feature request. Before, the impact table and the severity row disagreed, so a missing authentication method could read as Urgent on a Core path. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/issue-priority/SKILL.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.claude/skills/issue-priority/SKILL.md b/.claude/skills/issue-priority/SKILL.md index ba676e1a..d0400955 100644 --- a/.claude/skills/issue-priority/SKILL.md +++ b/.claude/skills/issue-priority/SKILL.md @@ -66,7 +66,7 @@ every ClickHouse client repository. An issue has none, one, or more of them: | Impact | Use when | | -------------- | -------- | -| Security | a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query, skips or weakens a TLS or identity check, or lets a remote party stop the client; also an authentication method that does not work or is missing | +| Security | a **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query, skips or weakens a TLS or identity check, or lets a remote party stop the client. Also **authentication**: an authentication method that does not work or is missing | | Data integrity | data that the caller wrote, or a result that the caller reads, is missing, incomplete, or different from the value given or stored, and the client reports no error; this includes a failed operation that the client reports as a success | | Stability | the process stops in a way that the caller cannot handle as a normal error, a call does not return, or a resource leaks until none is left | | Performance | the result is correct, but the operation is too slow, or uses too much memory or CPU | @@ -79,11 +79,17 @@ highest row applies: | Severity | Use when | | ----------------------- | -------- | -| Wrong data or security | impact **Data integrity**: the client returns or stores wrong or incomplete data with no error (this includes a block stream that goes out of sync with no error), or reports success for a query that failed; or impact **Security**: a security defect: a leak of credentials or data, a TLS verification that does not occur, SQL built from a caller value without escaping, or memory corruption (an out-of-bounds write, a use after free). A hang or a crash that only a hostile server or network causes does not use this row: rate it by the failure. A request for an authentication method is a feature request | +| Wrong data or security | impact **Data integrity**: the client returns or stores wrong or incomplete data with no error (this includes a block stream that goes out of sync with no error), or reports success for a query that failed; or impact **Security** with a vulnerability: a security defect: a leak of credentials or data, a TLS verification that does not occur, SQL built from a caller value without escaping, or memory corruption (an out-of-bounds write, a use after free). A hang or a crash that only a hostile server or network causes does not use this row: rate it by the failure | | Broken, no workaround | the feature fails (an exception, a hang, a crash, an abort, a leak that ends in a crash or in exhausted sockets), and the caller has no reasonable workaround; also a `Client` that stays unusable after an error, and a build that fails on a supported toolchain; also a wrong or incomplete error with no workaround: the failure is reported, but its type, code, or message is wrong or lost. The impact **Stability** (a hang, a crash, such a leak) uses this row when the caller has no reasonable workaround | | Workaround exists | the feature fails, but the caller can avoid the failure with a small change in their own code or build flags (name the workaround in the reason); also impact **Performance**: a result that is correct but slow or uses too much memory | | Cosmetic, docs, feature | wrong log or message text, a compiler warning, documentation, a feature request (this includes support for a new type or a new package manager) | +An issue that has the impact Security with no vulnerability (an authentication +method that does not work or is missing) does not use the first row. Rate an +authentication method that does not work by its failure ("Broken, no +workaround" or "Workaround exists"), and a request for a missing method as a +feature request. + ## 3. Base level | Severity ↓ / Reach → | Core | Common | Narrow | Satellite | From 164ff829c7769c6314cdaa6e5e777165d961ff56 Mon Sep 17 00:00:00 2001 From: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:47:47 +0000 Subject: [PATCH 04/11] docs(agents): handle vulnerabilities that are not public yet in issue priority A security issue must not stay public with a description of how to reproduce it. A confirmed vulnerability that is not public yet goes to a private GitHub vulnerability report; the public issue gets no Priority, and the rating goes into the report as the proposed severity. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/issue-priority/SKILL.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/.claude/skills/issue-priority/SKILL.md b/.claude/skills/issue-priority/SKILL.md index d0400955..3f1e6e41 100644 --- a/.claude/skills/issue-priority/SKILL.md +++ b/.claude/skills/issue-priority/SKILL.md @@ -38,6 +38,26 @@ Set no priority when one of these is true: - The issue is a question, or it is about CI, the release process, or a discussion. +## Vulnerabilities that are not public yet + +A security issue must not stay public with a description of how to reproduce +it. When a reproduction confirms a vulnerability that is not public yet +(credentials or data are exposed, a value changes the meaning of a query, a TLS +or identity check is skipped or weakened, or input that an untrusted party +controls stops the client): + +- Report it in a private GitHub vulnerability report for this repository + (**Security** → **Report a vulnerability**), not in a public issue or + comment. +- Set no Priority on the public issue. The issue is closed with a comment that + gives no details, and a repository administrator can delete it. +- Rate the vulnerability with the rules below, and put the level and its reason + into the private report as the proposed severity. + +A vulnerability that is already public (a published CVE or GHSA, for example in +a dependency), and an authentication method that does not work or is missing, +get a Priority on the issue as usual. + ## 1. Reach The reach is the tier of the most-used public path that reaches the defect, @@ -109,8 +129,9 @@ Apply them in this order: defect that puts a caller-supplied value into SQL without quoting or escaping is a candidate (for example a table name, a setting, or a query parameter): look for such a path. If none is shown, rate the defect by the - failure that it shows. A report that discloses a vulnerability goes to a - private channel, not to a public issue. + failure that it shows. A vulnerability that is not public yet goes to a + private vulnerability report, not to a public issue (see "Vulnerabilities + that are not public yet"). 2. **Regression in the latest published release**: up one level. This can give `Urgent`. It is a regression only when the latest release shows the problem and the release before it does not. The tags are `vX.Y.Z` (for example From 86e304918ff965825239774696b0a6eef98a2276 Mon Sep 17 00:00:00 2001 From: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:56:36 +0000 Subject: [PATCH 05/11] docs(agents): align the private-report rule with the security severity row Review feedback (Copilot on clickhouse-js#1155, Bugbot on clickhouse-cpp#613): - the private-report rule also applies when code inspection confirms the vulnerability; - copy the issue text into the private report, and ask an administrator to delete the issue: closing does not hide its text; - the impact Security names memory corruption, and input from the application's users that stops the client; a hang or a crash that only a hostile server or network causes is Stability. AGENTS.md: a vulnerability that is not public yet goes into a private security report, never into an issue or a pull request. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/issue-priority/SKILL.md | 23 ++++++++++++++--------- AGENTS.md | 1 + 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/.claude/skills/issue-priority/SKILL.md b/.claude/skills/issue-priority/SKILL.md index 3f1e6e41..5ec288cf 100644 --- a/.claude/skills/issue-priority/SKILL.md +++ b/.claude/skills/issue-priority/SKILL.md @@ -41,16 +41,21 @@ Set no priority when one of these is true: ## Vulnerabilities that are not public yet A security issue must not stay public with a description of how to reproduce -it. When a reproduction confirms a vulnerability that is not public yet -(credentials or data are exposed, a value changes the meaning of a query, a TLS -or identity check is skipped or weakened, or input that an untrusted party -controls stops the client): +it. This section applies when a reproduction or code inspection confirms a +vulnerability that is not public yet (impact Security, part vulnerability, in +section 2): a leak of credentials or data, a value that changes the meaning of +a query, a TLS or identity check that is skipped or weakened, memory +corruption, or input from the application's users that stops the client. A +hang or a crash that only a hostile server or network causes is not one: rate +it by the failure, as usual. - Report it in a private GitHub vulnerability report for this repository - (**Security** → **Report a vulnerability**), not in a public issue or - comment. -- Set no Priority on the public issue. The issue is closed with a comment that - gives no details, and a repository administrator can delete it. + (**Security** → **Report a vulnerability**), never in a public issue, + comment, or pull request. If a public issue reports it, copy the title, the + text, and the comments of the issue into the report first. +- Set no Priority on the public issue. Close it with a comment that gives no + details, and ask a repository administrator to delete it: closing does not + hide the text of the issue. - Rate the vulnerability with the rules below, and put the level and its reason into the private report as the proposed severity. @@ -86,7 +91,7 @@ every ClickHouse client repository. An issue has none, one, or more of them: | Impact | Use when | | -------------- | -------- | -| Security | a **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query, skips or weakens a TLS or identity check, or lets a remote party stop the client. Also **authentication**: an authentication method that does not work or is missing | +| Security | a **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query, skips or weakens a TLS or identity check, corrupts memory (an out-of-bounds write, a use after free), or lets input that the application takes from its users stop the client (a hang or a crash that only a hostile server or network causes is Stability). Also **authentication**: an authentication method that does not work or is missing | | Data integrity | data that the caller wrote, or a result that the caller reads, is missing, incomplete, or different from the value given or stored, and the client reports no error; this includes a failed operation that the client reports as a success | | Stability | the process stops in a way that the caller cannot handle as a normal error, a call does not return, or a resource leaks until none is left | | Performance | the result is correct, but the operation is too slow, or uses too much memory or CPU | diff --git a/AGENTS.md b/AGENTS.md index 4f6fc634..d11f9e6b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,3 +5,4 @@ # When triaging issues - To set, check, or explain the Priority of an issue, follow [`.claude/skills/issue-priority/SKILL.md`](.claude/skills/issue-priority/SKILL.md). It is the single source of truth for the priority rules. +- A vulnerability that is not public yet goes into a private security report (**Security** → **Report a vulnerability**), never into an issue or a pull request. The section "Vulnerabilities that are not public yet" of that skill says how to handle it. From 91f02b158d5891db0db0881f4e757487c061ed65 Mon Sep 17 00:00:00 2001 From: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:15:50 +0000 Subject: [PATCH 06/11] docs(agents): code inspection can show an impact in issue priority Review feedback (Bugbot on clickhouse-js#1155): the private-report rule accepts a vulnerability that code inspection confirms, but section 2 gave an impact only when the issue or a reproduction showed it. Section 2 now also accepts code inspection, as section 5 already does (confidence MEDIUM). Co-Authored-By: Claude Opus 5.5 --- .claude/skills/issue-priority/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/skills/issue-priority/SKILL.md b/.claude/skills/issue-priority/SKILL.md index 5ec288cf..15580d90 100644 --- a/.claude/skills/issue-priority/SKILL.md +++ b/.claude/skills/issue-priority/SKILL.md @@ -96,8 +96,8 @@ every ClickHouse client repository. An issue has none, one, or more of them: | Stability | the process stops in a way that the caller cannot handle as a normal error, a call does not return, or a resource leaks until none is left | | Performance | the result is correct, but the operation is too slow, or uses too much memory or CPU | -Give an impact only when the issue or a reproduction shows it. Most issues have -none. +Give an impact only when the issue, a reproduction, or code inspection of the +current code shows it. Most issues have none. Then use the first severity row that fits. With more than one impact, the highest row applies: From 9cbc47fdd57a5fa9b32179fe88a264012f33a43e Mon Sep 17 00:00:00 2001 From: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:17:16 +0000 Subject: [PATCH 07/11] docs(agents): memory corruption stays a vulnerability with a hostile server Security review (ConnectorSec on clickhouse-odbc#615): the exclusion "a hang or a crash that only a hostile server or network causes" also covered memory corruption, which a crafted server response causes and which anyone on the network path can send over plain HTTP. The exclusion now covers hangs and crashes with no memory corruption only, and a crash on server data must have memory corruption ruled out by code inspection before it is rated by its failure. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/issue-priority/SKILL.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/.claude/skills/issue-priority/SKILL.md b/.claude/skills/issue-priority/SKILL.md index 15580d90..7bea2388 100644 --- a/.claude/skills/issue-priority/SKILL.md +++ b/.claude/skills/issue-priority/SKILL.md @@ -44,10 +44,13 @@ A security issue must not stay public with a description of how to reproduce it. This section applies when a reproduction or code inspection confirms a vulnerability that is not public yet (impact Security, part vulnerability, in section 2): a leak of credentials or data, a value that changes the meaning of -a query, a TLS or identity check that is skipped or weakened, memory -corruption, or input from the application's users that stops the client. A -hang or a crash that only a hostile server or network causes is not one: rate -it by the failure, as usual. +a query, a TLS or identity check that is skipped or weakened, memory corruption +(also when only a hostile server or network causes it), or input from the +application's users that stops the client. A hang, or a crash with no memory +corruption, that only a hostile server or network causes is not one: rate it by +the failure, as usual. A crash while the client reads data from the server (for +example an access violation or `SIGSEGV`) can be memory corruption: rule that +out by code inspection before you rate it by the failure. - Report it in a private GitHub vulnerability report for this repository (**Security** → **Report a vulnerability**), never in a public issue, @@ -91,7 +94,7 @@ every ClickHouse client repository. An issue has none, one, or more of them: | Impact | Use when | | -------------- | -------- | -| Security | a **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query, skips or weakens a TLS or identity check, corrupts memory (an out-of-bounds write, a use after free), or lets input that the application takes from its users stop the client (a hang or a crash that only a hostile server or network causes is Stability). Also **authentication**: an authentication method that does not work or is missing | +| Security | a **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query, skips or weakens a TLS or identity check, corrupts memory (an out-of-bounds write, a use after free, also when only a hostile server or network causes it), or lets input that the application takes from its users stop the client (a hang, or a crash with no memory corruption, that only a hostile server or network causes is Stability). Also **authentication**: an authentication method that does not work or is missing | | Data integrity | data that the caller wrote, or a result that the caller reads, is missing, incomplete, or different from the value given or stored, and the client reports no error; this includes a failed operation that the client reports as a success | | Stability | the process stops in a way that the caller cannot handle as a normal error, a call does not return, or a resource leaks until none is left | | Performance | the result is correct, but the operation is too slow, or uses too much memory or CPU | @@ -104,7 +107,7 @@ highest row applies: | Severity | Use when | | ----------------------- | -------- | -| Wrong data or security | impact **Data integrity**: the client returns or stores wrong or incomplete data with no error (this includes a block stream that goes out of sync with no error), or reports success for a query that failed; or impact **Security** with a vulnerability: a security defect: a leak of credentials or data, a TLS verification that does not occur, SQL built from a caller value without escaping, or memory corruption (an out-of-bounds write, a use after free). A hang or a crash that only a hostile server or network causes does not use this row: rate it by the failure | +| Wrong data or security | impact **Data integrity**: the client returns or stores wrong or incomplete data with no error (this includes a block stream that goes out of sync with no error), or reports success for a query that failed; or impact **Security** with a vulnerability: a security defect: a leak of credentials or data, a TLS verification that does not occur, SQL built from a caller value without escaping, or memory corruption (an out-of-bounds write, a use after free). A hang, or a crash with no memory corruption, that only a hostile server or network causes does not use this row: rate it by the failure | | Broken, no workaround | the feature fails (an exception, a hang, a crash, an abort, a leak that ends in a crash or in exhausted sockets), and the caller has no reasonable workaround; also a `Client` that stays unusable after an error, and a build that fails on a supported toolchain; also a wrong or incomplete error with no workaround: the failure is reported, but its type, code, or message is wrong or lost. The impact **Stability** (a hang, a crash, such a leak) uses this row when the caller has no reasonable workaround | | Workaround exists | the feature fails, but the caller can avoid the failure with a small change in their own code or build flags (name the workaround in the reason); also impact **Performance**: a result that is correct but slow or uses too much memory | | Cosmetic, docs, feature | wrong log or message text, a compiler warning, documentation, a feature request (this includes support for a new type or a new package manager) | From 91f5c05383e4a8a2a57688214e5f6705202fc8b1 Mon Sep 17 00:00:00 2001 From: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:37:24 +0000 Subject: [PATCH 08/11] docs(agents): add the issue-classification skill; issue priority uses it Each ClickHouse client repository gets the same classification skill (.claude/skills/issue-classification/SKILL.md): the impacts (Security, Data integrity, Stability, Performance), the areas, the boundaries, the test for a vulnerability that is not public yet, and how to write the classification. Any agent can then classify an issue in the repository. A section "This repository" at the end holds local changes. The issue-priority skill no longer copies the impact definitions: it points to the classification skill and keeps the reach tiers, severity rows, matrix, modifiers, and the handling of a vulnerability. AGENTS.md points to both skills. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/issue-classification/SKILL.md | 171 +++++++++++++++++++ .claude/skills/issue-priority/SKILL.md | 44 ++--- AGENTS.md | 3 +- 3 files changed, 190 insertions(+), 28 deletions(-) create mode 100644 .claude/skills/issue-classification/SKILL.md diff --git a/.claude/skills/issue-classification/SKILL.md b/.claude/skills/issue-classification/SKILL.md new file mode 100644 index 00000000..2858784e --- /dev/null +++ b/.claude/skills/issue-classification/SKILL.md @@ -0,0 +1,171 @@ +--- +name: issue-classification +description: > + The classes of an issue in this ClickHouse client repository: the impacts + (Security, Data integrity, Stability, Performance) and the area (Connectivity, + Data types & formats, Queries, Configuration, API & diagnostics, Environment, + Docs & project, Other). Use this skill when the task is to "classify an + issue" or "give the classes of an issue", and when you triage, file, or + prioritize an issue: the issue-priority skill uses the impacts. +--- + +# Issue classification + +The classes name **what kind of problem an issue is about**, with the same words in every +ClickHouse client repo. They are an input to the priority, and they make issue counts +comparable across clients. + +An issue has: + +- **Impacts** — what goes wrong: none, one, or more of the four impact classes. +- **One area** — the part of the client whose behavior is wrong or missing. + +The classes do not replace the kind of request (bug, feature, question) or the reach tier of +a repo's priority rules. + +Every ClickHouse client repository has a copy of this file, so that any agent can classify an +issue in the repository. Keep the copies the same where you can, so that the classes mean the +same in every client. Put a change that applies only to this repository in the section "This +repository" at the end. + +## Rules + +1. Give each impact that applies, and one area. +2. Use only what the issue, a reproduction, or code inspection of the current code + **shows**. Do not give a class for an effect + that is only possible. Classes can raise the priority, so each class needs evidence. +3. Classify by the **observed effect**, not by the location of the code. Example: a + connection-string defect that makes the client drop rows with no error has the impact + Data integrity. +4. Data integrity and Stability are for defects only. Security and Performance are also for + feature requests: a new authentication method, a request to make an operation faster. +5. An issue with no harm has no impact. This is the normal case. + +## Impact classes + +| Impact | Use when | +|---|---| +| **Security** | Two parts. A **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query (injection), skips or weakens a TLS or identity check, corrupts memory (an out-of-bounds write, a use after free, also when only a hostile server or network causes it), or lets input that the application takes from its users stop the client; also a vulnerable dependency. A hang, or a crash with no memory corruption, that only a hostile server or network causes is Stability, not Security. **Authentication**: an authentication method that does not work or is missing, and the handling of secrets. Say which part applies: the priority rules of a repo rate the two parts differently. | +| **Data integrity** | Data that the caller wrote, or a result that the caller reads, is missing, incomplete, or different from the value given or stored, and the client reports no error. This includes a failed operation that the client reports as a success, a server error that the client ignores, overflow, lost precision, a time zone shift, a wrong decode, a stream that loses synchronization, a duplicate write, and a write to the wrong table. | +| **Stability** | The process stops in a way that the caller cannot handle as a normal error (abort, segmentation fault, unrecovered panic, stack overflow), a call does not return (deadlock, hang), or a resource leaks until none is left (connections, sockets, memory). Also a thread-safety defect. | +| **Performance** | The result is correct, but the operation is too slow, or uses too much memory or CPU. Also a request to make an operation faster. | + +Boundaries: + +- **Data integrity needs "no error".** When the client rejects a value with an error, the + issue has no Data integrity impact. When the caller gets an error, but the error is wrong + or not clear, the issue has no Data integrity impact either: it has the area API & + diagnostics. +- **Security and values that are not quoted.** A value or an identifier that the client + does not quote or escape gets Security only when the issue shows a path from untrusted + input. A string value that leaves its literal because the client does not escape it is + such a path. An identifier that the client does not quote, with no such path, is the area + Queries with no impact. +- **TLS.** A TLS check that the client skips or weakens is Security. A connection with TLS + that fails has no impact; its area is Connectivity. +- **Memory.** High memory use without a failure is Performance, not Stability. +- **An error is not Stability.** A normal exception or error value is not a crash. In Go + and Rust, a panic that the library does not recover is Stability. In Java, a + `StackOverflowError`, `OutOfMemoryError`, or `VerifyError` is Stability. + +## A vulnerability that is not public yet + +A security issue must not stay public with a description of how to reproduce it. An issue +is a **confirmed vulnerability** when a run or code inspection shows one of these: + +- credentials or data are exposed to a party that must not get them; +- a value changes the meaning of a query (injection); +- a TLS or identity check is skipped or weakened; +- memory corruption (an out-of-bounds write, a use after free), also when only a hostile + server or network causes it; +- input that the application takes from its users stops the client. + +A hang, or a crash with no memory corruption, that only a hostile server or network causes is +not a vulnerability: it is Stability, and it is triaged in public. A crash while the client +reads data from the server (for example an access violation or `SIGSEGV`) can be memory +corruption: rule that out by code inspection before you treat it as Stability. + +Never put a confirmed vulnerability into a public comment, issue, pull request, or +Classification line. Report it in a private GitHub vulnerability report for this repository +(**Security** → **Report a vulnerability**). The issue-priority skill of this repository says +how to handle the public issue and how to rate the vulnerability. When you can neither confirm +nor rule out a vulnerability, do not discuss it in public either: ask a maintainer in private, +or send a private report that says what is not confirmed. + +These are not affected: a vulnerability that is already public (a published CVE or GHSA, for +example in a dependency), and the part authentication (a method that does not work or is +missing). Classify them as usual. + +## Area classes + +| Area | Scope | +|---|---| +| **Connectivity** | Connect and handshake, a connection with TLS, proxies and redirects, the connection pool, keep-alive, reconnect and failover, retries, timeouts, cancellation, the transport (HTTP, native TCP), compression on the wire. | +| **Data types & formats** | Parsing of type names, encoding and decoding of values, the mapping to language types and to rows or objects (POJO, serde, struct), data formats (Native, RowBinary, JSON, Parquet, Arrow), support for a new type or format. | +| **Queries** | How the client builds a statement: parameters and placeholders, quoting and escaping, SQL parsing in the client, size limits of the statement and its parameters. How the client runs a statement: batches and streaming inserts, sessions and roles, external data, totals, asynchronous inserts, the queries that the client sends on its own (`DESCRIBE`, server information), caches of table structure. | +| **Configuration** | Reading and passing options: connection strings, DSNs, URLs, and option objects (parsing, validation, defaults); ClickHouse settings for a connection or a query; settings that the client sends on its own. | +| **API & diagnostics** | The shape of the public API (a missing method or overload, a wrong type signature), and conformance to a standard interface that the client implements (JDBC, ODBC, ADO.NET, `database/sql`, DB-API, SQLAlchemy, R2DBC), including metadata and catalog functions. Errors that are wrong, incomplete, or not clear. Logging, metrics, tracing, progress, the query ID. | +| **Environment** | A build from sources, support for a compiler, runtime, operating system, or architecture, package managers, released artifacts, installers, dependencies. Also a failure with one ClickHouse server version only, or with one third-party tool only (Power BI, Tableau, Spark, DBeaver). | +| **Docs & project** | Documentation, examples, or the changelog are wrong or missing. Tests, CI, the release process, refactoring. | +| **Other** | No area fits. | + +Boundaries: + +- **Configuration or the area that an option controls.** If the client reads an option + correctly but the behavior that the option controls is wrong, use the area of that + behavior. Example: a keep-alive option that has no effect is Connectivity. +- **Authentication.** An authentication issue has the impact Security and the area + Connectivity. +- **Environment or the area of the failure.** Use Environment when the same call works in + general, and fails only with one server version, one platform, or one third-party tool. + A failure with all server versions and without the tool has the area of the failure. +- **API & diagnostics or the area of the failure.** When the problem is the quality of an + error, use API & diagnostics. When the problem is that the operation fails at all, use + the area of the operation. + +Rules for **Other**: + +- Other is the last choice. Say why no area fits. +- Other does not raise the priority. +- A subject that repeats in Other is a sign that a class is missing: report it. + +## Examples + +| Issue | Impacts | Area | +|---|---|---| +| A bare `Enum(...)` type hint is written as `Enum8`, which corrupts the data | Data integrity | Data types & formats | +| A flush returns no error when the server rejects the INSERT | Data integrity | Queries | +| The connection pool leaks connections until none is left | Stability | Connectivity | +| String parameters are not escaped | Security (vulnerability) | Queries | +| `LowCardinality(Nullable(String))` cannot be read: the client returns an error | none | Data types & formats | +| A server error loses its code when the response arrives in two chunks | none | API & diagnostics | +| A request for Kerberos authentication | Security (authentication) | Connectivity | +| Each compressed read fails on one new server version | none | Environment | +| Parameter binding takes quadratic time | Performance | Queries | + +## How to write the classification + +One line, in this form. In a triage comment, the line has the name **Classification**: + +`impact: · area: ()` + +For Security, add the part in parentheses: `Security (vulnerability)` or +`Security (authentication)`. + +The **subject** names what the issue is about inside the area, in one to four words. Use the +names that ClickHouse or the client API uses: + +- **Data types & formats:** always the ClickHouse types or the data format, for example + `(Enum8, Enum16)`, `(Map)`, `(DateTime64)`, `(RowBinary)`, `(Parquet)`. "Data types & + formats" alone does not say which type. +- **Other areas:** the feature, for example `(cancellation)`, `(TLS)`, `(connection pool)`, + `(query parameters)`, `(sessions)`, `(mid-stream errors)`, `(logging)`, `(release process)`. +- With two areas, give a subject after each one. + +Examples: `impact: Data integrity · area: Data types & formats (Map)`, +`impact: none · area: Configuration (URL parameters)`, +`impact: Security (vulnerability), Stability · area: Connectivity (TLS)`. + +## This repository + +No changes to the shared text. diff --git a/.claude/skills/issue-priority/SKILL.md b/.claude/skills/issue-priority/SKILL.md index 7bea2388..d70aa299 100644 --- a/.claude/skills/issue-priority/SKILL.md +++ b/.claude/skills/issue-priority/SKILL.md @@ -1,12 +1,12 @@ --- name: issue-priority description: > - Decide the priority of a `ClickHouse/clickhouse-cpp` issue: `Urgent`, `High`, - `Medium`, or `Low`, for the org issue field **Priority**. Use this skill when - the task is to "prioritize", "set the priority of", "rate", or "triage" an - issue, or to explain why an issue has a given priority. It defines the reach - tiers of the library, the impact classes, the severity rows, the base-level matrix, the - modifiers, and the confidence. + Decide the priority of a `ClickHouse/clickhouse-cpp` issue: `Urgent`, + `High`, `Medium`, or `Low`, for the org issue field **Priority**. Use this + skill when the task is to "prioritize", "set the priority of", "rate", or + "triage" an issue, or to explain why an issue has a given priority. It + defines the reach tiers of the library, the severity rows, the base-level + matrix, the modifiers, and the confidence. --- # Issue priority @@ -42,15 +42,12 @@ Set no priority when one of these is true: A security issue must not stay public with a description of how to reproduce it. This section applies when a reproduction or code inspection confirms a -vulnerability that is not public yet (impact Security, part vulnerability, in -section 2): a leak of credentials or data, a value that changes the meaning of -a query, a TLS or identity check that is skipped or weakened, memory corruption -(also when only a hostile server or network causes it), or input from the -application's users that stops the client. A hang, or a crash with no memory -corruption, that only a hostile server or network causes is not one: rate it by -the failure, as usual. A crash while the client reads data from the server (for -example an access violation or `SIGSEGV`) can be memory corruption: rule that -out by code inspection before you rate it by the failure. +vulnerability that is not public yet. The classification skill of this +repository defines it +([`../issue-classification/SKILL.md`](../issue-classification/SKILL.md), "A +vulnerability that is not public yet"): memory corruption is one also when only +a hostile server or network causes it, and a hang, or a crash with no memory +corruption, that only such a server or network causes is not one. - Report it in a private GitHub vulnerability report for this repository (**Security** → **Report a vulnerability**), never in a public issue, @@ -89,18 +86,11 @@ build flag `-DCH_USE_ABSEIL_FOR_BIGNUM=OFF` (severity "Workaround exists"). ## 2. Severity -First name the **impacts** of the issue. The impact classes are the same in -every ClickHouse client repository. An issue has none, one, or more of them: - -| Impact | Use when | -| -------------- | -------- | -| Security | a **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query, skips or weakens a TLS or identity check, corrupts memory (an out-of-bounds write, a use after free, also when only a hostile server or network causes it), or lets input that the application takes from its users stop the client (a hang, or a crash with no memory corruption, that only a hostile server or network causes is Stability). Also **authentication**: an authentication method that does not work or is missing | -| Data integrity | data that the caller wrote, or a result that the caller reads, is missing, incomplete, or different from the value given or stored, and the client reports no error; this includes a failed operation that the client reports as a success | -| Stability | the process stops in a way that the caller cannot handle as a normal error, a call does not return, or a resource leaks until none is left | -| Performance | the result is correct, but the operation is too slow, or uses too much memory or CPU | - -Give an impact only when the issue, a reproduction, or code inspection of the -current code shows it. Most issues have none. +First name the **impacts** of the issue with the classification skill of this +repository +([`../issue-classification/SKILL.md`](../issue-classification/SKILL.md)): none, +one, or more of Security (part vulnerability or part authentication), Data +integrity, Stability, and Performance. Most issues have none. Then use the first severity row that fits. With more than one impact, the highest row applies: diff --git a/AGENTS.md b/AGENTS.md index d11f9e6b..be71d59a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,4 +5,5 @@ # When triaging issues - To set, check, or explain the Priority of an issue, follow [`.claude/skills/issue-priority/SKILL.md`](.claude/skills/issue-priority/SKILL.md). It is the single source of truth for the priority rules. -- A vulnerability that is not public yet goes into a private security report (**Security** → **Report a vulnerability**), never into an issue or a pull request. The section "Vulnerabilities that are not public yet" of that skill says how to handle it. +- To classify an issue (its impacts and its area), follow [`.claude/skills/issue-classification/SKILL.md`](.claude/skills/issue-classification/SKILL.md). +- A vulnerability that is not public yet goes into a private security report (**Security** → **Report a vulnerability**), never into an issue or a pull request. The classification skill defines such a vulnerability, and the priority skill says how to handle the public issue. From 4a6cd316c34ca42ea492f95c2bb06df2d580c4f3 Mon Sep 17 00:00:00 2001 From: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:49:41 +0000 Subject: [PATCH 09/11] docs(agents): rate speed requests and dependency CVEs; leaked secrets are vulnerabilities Review feedback (Bugbot on clickhouse-cpp#613): - a request to make an operation faster has the impact Performance but is a feature request ("Cosmetic, docs, feature"); only a Performance defect uses "Workaround exists"; - authentication means how the client takes credentials; a secret that leaks is a vulnerability, not authentication; - a dependency with a published CVE or GHSA uses "Wrong data or security" when the client calls the vulnerable code, else it is a dependency update; an unpublished dependency vulnerability goes to the private report. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/issue-classification/SKILL.md | 5 ++++- .claude/skills/issue-priority/SKILL.md | 10 +++++++++- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/.claude/skills/issue-classification/SKILL.md b/.claude/skills/issue-classification/SKILL.md index 2858784e..d2b31b8a 100644 --- a/.claude/skills/issue-classification/SKILL.md +++ b/.claude/skills/issue-classification/SKILL.md @@ -39,13 +39,14 @@ repository" at the end. Data integrity. 4. Data integrity and Stability are for defects only. Security and Performance are also for feature requests: a new authentication method, a request to make an operation faster. + The priority rules rate such requests as feature requests. 5. An issue with no harm has no impact. This is the normal case. ## Impact classes | Impact | Use when | |---|---| -| **Security** | Two parts. A **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query (injection), skips or weakens a TLS or identity check, corrupts memory (an out-of-bounds write, a use after free, also when only a hostile server or network causes it), or lets input that the application takes from its users stop the client; also a vulnerable dependency. A hang, or a crash with no memory corruption, that only a hostile server or network causes is Stability, not Security. **Authentication**: an authentication method that does not work or is missing, and the handling of secrets. Say which part applies: the priority rules of a repo rate the two parts differently. | +| **Security** | Two parts. A **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query (injection), skips or weakens a TLS or identity check, corrupts memory (an out-of-bounds write, a use after free, also when only a hostile server or network causes it), or lets input that the application takes from its users stop the client; also a dependency with a published vulnerability (CVE or GHSA) in code that the client calls. A hang, or a crash with no memory corruption, that only a hostile server or network causes is Stability, not Security. **Authentication**: an authentication method that does not work or is missing, or how the client takes credentials (for example a token provider or a credentials file). A secret that leaks (to a log, an error message, a URL, or another host) is a vulnerability, not authentication. Say which part applies: the priority rules of a repo rate the two parts differently. | | **Data integrity** | Data that the caller wrote, or a result that the caller reads, is missing, incomplete, or different from the value given or stored, and the client reports no error. This includes a failed operation that the client reports as a success, a server error that the client ignores, overflow, lost precision, a time zone shift, a wrong decode, a stream that loses synchronization, a duplicate write, and a write to the wrong table. | | **Stability** | The process stops in a way that the caller cannot handle as a normal error (abort, segmentation fault, unrecovered panic, stack overflow), a call does not return (deadlock, hang), or a resource leaks until none is left (connections, sockets, memory). Also a thread-safety defect. | | **Performance** | The result is correct, but the operation is too slow, or uses too much memory or CPU. Also a request to make an operation faster. | @@ -78,6 +79,8 @@ is a **confirmed vulnerability** when a run or code inspection shows one of thes - a TLS or identity check is skipped or weakened; - memory corruption (an out-of-bounds write, a use after free), also when only a hostile server or network causes it; +- a vulnerability in a dependency that is not published yet (also report it to the + maintainers of that dependency); - input that the application takes from its users stops the client. A hang, or a crash with no memory corruption, that only a hostile server or network causes is diff --git a/.claude/skills/issue-priority/SKILL.md b/.claude/skills/issue-priority/SKILL.md index d70aa299..b0c7c4c2 100644 --- a/.claude/skills/issue-priority/SKILL.md +++ b/.claude/skills/issue-priority/SKILL.md @@ -97,7 +97,7 @@ highest row applies: | Severity | Use when | | ----------------------- | -------- | -| Wrong data or security | impact **Data integrity**: the client returns or stores wrong or incomplete data with no error (this includes a block stream that goes out of sync with no error), or reports success for a query that failed; or impact **Security** with a vulnerability: a security defect: a leak of credentials or data, a TLS verification that does not occur, SQL built from a caller value without escaping, or memory corruption (an out-of-bounds write, a use after free). A hang, or a crash with no memory corruption, that only a hostile server or network causes does not use this row: rate it by the failure | +| Wrong data or security | impact **Data integrity**: the client returns or stores wrong or incomplete data with no error (this includes a block stream that goes out of sync with no error), or reports success for a query that failed; or impact **Security** with a vulnerability: a security defect: a leak of credentials or data, a TLS verification that does not occur, SQL built from a caller value without escaping, memory corruption (an out-of-bounds write, a use after free), or a vulnerable dependency in code that the client calls. A hang, or a crash with no memory corruption, that only a hostile server or network causes does not use this row: rate it by the failure | | Broken, no workaround | the feature fails (an exception, a hang, a crash, an abort, a leak that ends in a crash or in exhausted sockets), and the caller has no reasonable workaround; also a `Client` that stays unusable after an error, and a build that fails on a supported toolchain; also a wrong or incomplete error with no workaround: the failure is reported, but its type, code, or message is wrong or lost. The impact **Stability** (a hang, a crash, such a leak) uses this row when the caller has no reasonable workaround | | Workaround exists | the feature fails, but the caller can avoid the failure with a small change in their own code or build flags (name the workaround in the reason); also impact **Performance**: a result that is correct but slow or uses too much memory | | Cosmetic, docs, feature | wrong log or message text, a compiler warning, documentation, a feature request (this includes support for a new type or a new package manager) | @@ -108,6 +108,14 @@ authentication method that does not work by its failure ("Broken, no workaround" or "Workaround exists"), and a request for a missing method as a feature request. +A request to make an operation faster has the impact Performance, but it is a +feature request: use "Cosmetic, docs, feature". Only a defect with the impact +Performance (a correct result that is too slow) uses "Workaround exists". + +A dependency with a published vulnerability (a CVE or GHSA) uses "Wrong data or +security" when the client calls the vulnerable code. When it does not, the +issue asks for a dependency update: use "Cosmetic, docs, feature". + ## 3. Base level | Severity ↓ / Reach → | Core | Common | Narrow | Satellite | From 791a959751b49cd6be2cd7e62c642d181f9c9e08 Mon Sep 17 00:00:00 2001 From: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com> Date: Wed, 18 Nov 2026 19:02:25 +0000 Subject: [PATCH 10/11] docs(agents): unpublished dependency vulnerabilities; report upstream in private Review feedback (Bugbot on clickhouse-odbc#615): the impact Security and the priority mapping named only a published CVE or GHSA, so an unpublished dependency vulnerability had no Security mapping; and the report to the dependency's maintainers did not say that it must be private. Both now cover a published or unpublished vulnerability, and the upstream report goes through the dependency's security policy, never a public issue. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/issue-classification/SKILL.md | 5 +++-- .claude/skills/issue-priority/SKILL.md | 7 ++++--- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/.claude/skills/issue-classification/SKILL.md b/.claude/skills/issue-classification/SKILL.md index d2b31b8a..1d1de2dc 100644 --- a/.claude/skills/issue-classification/SKILL.md +++ b/.claude/skills/issue-classification/SKILL.md @@ -46,7 +46,7 @@ repository" at the end. | Impact | Use when | |---|---| -| **Security** | Two parts. A **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query (injection), skips or weakens a TLS or identity check, corrupts memory (an out-of-bounds write, a use after free, also when only a hostile server or network causes it), or lets input that the application takes from its users stop the client; also a dependency with a published vulnerability (CVE or GHSA) in code that the client calls. A hang, or a crash with no memory corruption, that only a hostile server or network causes is Stability, not Security. **Authentication**: an authentication method that does not work or is missing, or how the client takes credentials (for example a token provider or a credentials file). A secret that leaks (to a log, an error message, a URL, or another host) is a vulnerability, not authentication. Say which part applies: the priority rules of a repo rate the two parts differently. | +| **Security** | Two parts. A **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query (injection), skips or weakens a TLS or identity check, corrupts memory (an out-of-bounds write, a use after free, also when only a hostile server or network causes it), or lets input that the application takes from its users stop the client; also a vulnerability in a dependency, in code that the client calls (published as a CVE or GHSA, or not published yet). A hang, or a crash with no memory corruption, that only a hostile server or network causes is Stability, not Security. **Authentication**: an authentication method that does not work or is missing, or how the client takes credentials (for example a token provider or a credentials file). A secret that leaks (to a log, an error message, a URL, or another host) is a vulnerability, not authentication. Say which part applies: the priority rules of a repo rate the two parts differently. | | **Data integrity** | Data that the caller wrote, or a result that the caller reads, is missing, incomplete, or different from the value given or stored, and the client reports no error. This includes a failed operation that the client reports as a success, a server error that the client ignores, overflow, lost precision, a time zone shift, a wrong decode, a stream that loses synchronization, a duplicate write, and a write to the wrong table. | | **Stability** | The process stops in a way that the caller cannot handle as a normal error (abort, segmentation fault, unrecovered panic, stack overflow), a call does not return (deadlock, hang), or a resource leaks until none is left (connections, sockets, memory). Also a thread-safety defect. | | **Performance** | The result is correct, but the operation is too slow, or uses too much memory or CPU. Also a request to make an operation faster. | @@ -80,7 +80,8 @@ is a **confirmed vulnerability** when a run or code inspection shows one of thes - memory corruption (an out-of-bounds write, a use after free), also when only a hostile server or network causes it; - a vulnerability in a dependency that is not published yet (also report it to the - maintainers of that dependency); + maintainers of that dependency in private, through their security policy, never in a + public issue); - input that the application takes from its users stops the client. A hang, or a crash with no memory corruption, that only a hostile server or network causes is diff --git a/.claude/skills/issue-priority/SKILL.md b/.claude/skills/issue-priority/SKILL.md index b0c7c4c2..53c5c8c0 100644 --- a/.claude/skills/issue-priority/SKILL.md +++ b/.claude/skills/issue-priority/SKILL.md @@ -112,9 +112,10 @@ A request to make an operation faster has the impact Performance, but it is a feature request: use "Cosmetic, docs, feature". Only a defect with the impact Performance (a correct result that is too slow) uses "Workaround exists". -A dependency with a published vulnerability (a CVE or GHSA) uses "Wrong data or -security" when the client calls the vulnerable code. When it does not, the -issue asks for a dependency update: use "Cosmetic, docs, feature". +A vulnerability in a dependency (published as a CVE or GHSA, or not published +yet) uses "Wrong data or security" when the client calls the vulnerable code. +When it does not, the issue asks for a dependency update: use "Cosmetic, docs, +feature". ## 3. Base level From 2e9e041a07ef2ba8e9dbbbfab0cf5d8a899eec05 Mon Sep 17 00:00:00 2001 From: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com> Date: Wed, 18 Nov 2026 19:24:54 +0000 Subject: [PATCH 11/11] docs(agents): an unpublished dependency vulnerability stays private Review feedback (Bugbot on clickhouse-odbc#615): the classification kept every unpublished dependency vulnerability private, but the severity rule rated one in code that the client does not call as a public dependency update. Now an unpublished one stays private also then; the low level is only the proposed severity of the private report. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/issue-classification/SKILL.md | 8 ++++---- .claude/skills/issue-priority/SKILL.md | 10 ++++++---- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/.claude/skills/issue-classification/SKILL.md b/.claude/skills/issue-classification/SKILL.md index 1d1de2dc..b7b7fdec 100644 --- a/.claude/skills/issue-classification/SKILL.md +++ b/.claude/skills/issue-classification/SKILL.md @@ -46,7 +46,7 @@ repository" at the end. | Impact | Use when | |---|---| -| **Security** | Two parts. A **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query (injection), skips or weakens a TLS or identity check, corrupts memory (an out-of-bounds write, a use after free, also when only a hostile server or network causes it), or lets input that the application takes from its users stop the client; also a vulnerability in a dependency, in code that the client calls (published as a CVE or GHSA, or not published yet). A hang, or a crash with no memory corruption, that only a hostile server or network causes is Stability, not Security. **Authentication**: an authentication method that does not work or is missing, or how the client takes credentials (for example a token provider or a credentials file). A secret that leaks (to a log, an error message, a URL, or another host) is a vulnerability, not authentication. Say which part applies: the priority rules of a repo rate the two parts differently. | +| **Security** | Two parts. A **vulnerability**: a defect makes the protection weaker: it exposes credentials or data, lets a value change the meaning of a query (injection), skips or weakens a TLS or identity check, corrupts memory (an out-of-bounds write, a use after free, also when only a hostile server or network causes it), or lets input that the application takes from its users stop the client; also a vulnerability in a dependency: a published one (CVE or GHSA) in code that the client calls, and any one that is not published yet. A hang, or a crash with no memory corruption, that only a hostile server or network causes is Stability, not Security. **Authentication**: an authentication method that does not work or is missing, or how the client takes credentials (for example a token provider or a credentials file). A secret that leaks (to a log, an error message, a URL, or another host) is a vulnerability, not authentication. Say which part applies: the priority rules of a repo rate the two parts differently. | | **Data integrity** | Data that the caller wrote, or a result that the caller reads, is missing, incomplete, or different from the value given or stored, and the client reports no error. This includes a failed operation that the client reports as a success, a server error that the client ignores, overflow, lost precision, a time zone shift, a wrong decode, a stream that loses synchronization, a duplicate write, and a write to the wrong table. | | **Stability** | The process stops in a way that the caller cannot handle as a normal error (abort, segmentation fault, unrecovered panic, stack overflow), a call does not return (deadlock, hang), or a resource leaks until none is left (connections, sockets, memory). Also a thread-safety defect. | | **Performance** | The result is correct, but the operation is too slow, or uses too much memory or CPU. Also a request to make an operation faster. | @@ -79,9 +79,9 @@ is a **confirmed vulnerability** when a run or code inspection shows one of thes - a TLS or identity check is skipped or weakened; - memory corruption (an out-of-bounds write, a use after free), also when only a hostile server or network causes it; -- a vulnerability in a dependency that is not published yet (also report it to the - maintainers of that dependency in private, through their security policy, never in a - public issue); +- a vulnerability in a dependency that is not published yet, also in code that the client + does not call (also report it to the maintainers of that dependency in private, through + their security policy, never in a public issue); - input that the application takes from its users stops the client. A hang, or a crash with no memory corruption, that only a hostile server or network causes is diff --git a/.claude/skills/issue-priority/SKILL.md b/.claude/skills/issue-priority/SKILL.md index 53c5c8c0..07e3bab9 100644 --- a/.claude/skills/issue-priority/SKILL.md +++ b/.claude/skills/issue-priority/SKILL.md @@ -112,10 +112,12 @@ A request to make an operation faster has the impact Performance, but it is a feature request: use "Cosmetic, docs, feature". Only a defect with the impact Performance (a correct result that is too slow) uses "Workaround exists". -A vulnerability in a dependency (published as a CVE or GHSA, or not published -yet) uses "Wrong data or security" when the client calls the vulnerable code. -When it does not, the issue asks for a dependency update: use "Cosmetic, docs, -feature". +A vulnerability in a dependency uses "Wrong data or security" when the client +calls the vulnerable code. When it does not, use "Cosmetic, docs, feature": for +a published one (a CVE or GHSA), the issue asks for a dependency update. One +that is not published yet stays private also then (see "Vulnerabilities that +are not public yet"), and this level is the proposed severity of the private +report. ## 3. Base level