Being entrusted by the commander of the codepatrol skill,.dev/codepatrol/ investigation target list for targets.md and perspective list checklist.md are generated and updated.
Which one to generate or update follows the commander's instructions.
Prerequisites for running this skill
- The conditions of the execution environment are the same as codepatrol skill 's "Confirmation of the execution environment". Check them yourself before starting, and if they are not met, generate nothing, report the unmet conditions, and exit
- Cannot ask the user questions. Matters that cannot be judged are written in the final report
- The locations for reading each repository's code and,
.dev/codepatrol/the location follow the commander's instructions. When there are related repositories, their names and domain name prefixes also follow the commander's instructions. Do not switch branches, pull, or commit
Configuration file format
At the beginning of targets.md and checklist.md, write Format: {現在の値} . The current value is 2.
The format changes with skill updates. When the value in either file differs from the current value or is absent, the commander entrusts the update of both. When updating an existing file with a different format, recreate it in the new format and carry over the existing domains, mechanism facts, and unique perspectives. Perspectives are matched by content, not by number.Format In the old format without the record of , unique perspectives continued the master's number sequence, so the same number points to a different perspective. Old items that cannot be expressed as supplements to the master are kept as unique perspectives. In old-format files without a list of related repositories, existing domains are carried over as those of the repository where the configuration is placed.
Generation and updating of targets.md
There are two types of investigation domains.
- Entry-point-based domains: Detected by scanning server-side entry points. Primarily responsible for the protection of the entry point itself
- Usage-end-event-based domains: Cut at events where usage, affiliation, contract, authority, or integration ends or shrinks. Entry-point-based domains have no one primarily responsible for pointing out "the processing that should exist is missing," so domains cut at events are primarily responsible for consistency between entry points and between storage locations
In the repository where the configuration is placed, the targets of automatic detection are limited to the server side. If other domains such as client/config/infra are needed, the user adds them manually to targets.md.
Related repositories
The commander may pass other repositories that make up the same service as related repositories. For each related repository, perform the same entry-point-based scan as for the repository where the configuration is placed, and start the domain name with the prefix passed from the commander to distinguish which repository the domain belongs to. At the beginning of the domain body, write "Repository: {name}", and if there is a domain of another repository that forms a pair, write its name. Paired domains are domains that handle the same entry point or data from both sides, where roles are divided at the repository boundary, such as receiving uploads and storing binaries. Paths are written relative to the root of the repository for that domain.
For related repositories that do not have a server-side entry point, such as infrastructure configuration, define domains by units of configuration that affect the outside, instead of by entry points. These units include definitions of secrets and permissions, network reach, deployment definitions, and data store configuration. Write in the domain body what is written in the configuration and to what extent, and what is outside the repository.
Do not add a prefix to domains based on usage-end events. Since events cross repository boundaries, enumerate units also from the data models of related repositories, and combine the entry points and assets of the same unit across repositories into a single domain. When there are related repositories, always add the repository name to the path of this domain.
Client repositories are excluded from automatic detection, and domains are added manually by the user.
During the scan, if you find clues about another repository not included in the related repositories, list them as candidates in the final report. Clues include host names of other services, API clients, other images referenced by deploy definitions, and mechanisms for client distribution and updates. Do not create domains for candidates.
Entry-point-based domain
Investigate the repository structure and detect investigation domains:
- Understand the framework and the location of server-side code from package.json, Gemfile, go.mod, etc.
- Enumerate server-side entry points, that is, locations that accept input from outside. Only those present in the repository are needed:
- HTTP routing and the controllers/handlers it references
- Handlers for real-time communication such as WebSocket
- Cross-cutting middleware/filters such as authentication, authorization, CSRF, rate limit, etc.
- Entry points for external input not covered above, such as webhook reception, batches, jobs, etc.
Guidelines for grouping domains:
- In principle, one directory containing controllers/handlers = one domain
- Single-file controllers may be grouped together with related ones
- Cross-cutting middleware/filters such as authentication and authorization should be made into one domain
- Real-time communication such as WebSocket should be made into one domain
Domain based on usage-end events
From the data model, list the units that have termination or reduction events. Typical ones are user accounts, tenants such as teams, projects, and organizations, contracts and plans, and major resources such as images, pages, and files. Make one section per unit, and start the name with lifecycle- . The investigator uses this prefix to switch investigation methods.
In the body of each section, write the following:
- Entry points for the trigger event. Include Web, API, admin screens, jobs, and notifications from external services. Include not only termination but also reductions such as removing members, downgrading plans, and disconnecting integrations. For events that are in promises or terms but whose entry point cannot be found, also include them by writing that they cannot be found
- The start side. Where the assets, permissions, and integrations whose handling at termination should be confirmed are created
- Sources of expectations. The display locations where promises to users are written, and the documents in the repository about retention policies and design. Display locations are screen text, terms of service, help, admin screen notices, etc., and since expressions may differ by language, list them together, and for those whose body is outside the repository, write that fact
- Related sections. Sections whose files overlap. Write both overlaps between lifecycle sections and sections of related repositories
The lifecycle section shares files with other sections. Write that at the beginning of targets.md. It becomes material for the commander to decide which groups to investigate in parallel.
Writing out
Write the detected sections to .dev/codepatrol/targets.md . Since section names become part of file names or page titles, keep them within alphanumerics, hyphens, and underscores, and do not include path separators or spaces. Format:
# Codepatrol Investigation Targets
Format: {現在の値}
Generated at: {YYYY-MM-DD HH:mm:ss}
Generated by: {Agent名 (model名)}, with {Codexの実行環境}
Source commit: {設定を置くリポジトリの、読んだcommitのshort hash}
Source commit ({関連リポジトリ名}): {そのリポジトリの、読んだcommitのshort hash}
各H2見出しが調査領域名。この名前がレポート名の一部になる。
領域を追加・分割・統合する場合はこのファイルを手動で編集する。
`lifecycle-` で始まる領域は利用終了イベントで切った領域で、ファイルは他の領域と重なる。
**関連リポジトリ**: 以下のリポジトリも調査の対象で、領域名の接頭辞で区別する。cloneの場所は開発者ごとに違うので、このファイルには書かない。
- {関連リポジトリ名}: {1行の役割}。領域名は `{接頭辞}-` で始まる。 {GitHub URL}
## {領域名}
{対象ディレクトリ/ファイルのパス}
{主なファイルの列挙}
## {接頭辞}-{領域名}
リポジトリ: {関連リポジトリ名}。{対になる別のリポジトリの領域と、役割の分かれ方}
{そのリポジトリのrootからの相対パス}
{主なファイルの列挙}
## lifecycle-{単位}
{単位と、終了・縮小のイベントの説明}
- 起点イベントの入口: {入口の列挙}
- 開始側: {資産・権限・連携が作られる場所}
- 期待値の出典: {表示箇所・言語・適用イベント}
- 関連する領域: {ファイルが重なる領域名}
When there is no related repository,Source commit ({関連リポジトリ名}) omit the line and the related repository paragraph.
When updating an existing targets.md:
Read the existing targets.md and compare it with the new scan results.
- Keep the existing H2 headings (section names). Do not break the results of manual splitting or merging by the user
- The explanatory text under existing H2 headings may be updated based on the scan results
- Add newly detected sections as H2 headings at the end
- Do not delete sections that no longer correspond to the scan results (such as due to directory deletion); leave them. The user decides and deletes them
- When a related repository is removed by the commander's instruction, delete that repository's sections together with the header list. Existing reports remain as they are
Generation and update of checklist.md
In the same directory as this SKILL.md, CHECKLIST.md is a master of perspectives that does not depend on a specific repository, and is not rewritten.
.dev/codepatrol/checklist.md is a repository-specific layer, and the investigator reads it together with the master. Do not copy the master's perspective sentences. If copied, old sentences remain when the perspectives change due to a skill update.
- CHECKLIST.md Load
- Investigate the repository's security mechanisms. The specific names of authorization middleware and role hierarchies, the unit of tenant boundaries (project, team, organization, etc.), the authentication and session management methods, the template engine and client rendering methods, the DB access layer, file storage, locations that send requests externally, the rate limit implementation, and business logic such as billing
- If there are related repositories, investigate each of their mechanisms from the same perspective. For calls between repositories, also capture as facts of the mechanism which side handles authentication and authorization, and what is trusted and received
- The purpose of this investigation is to supplement the perspectives with specific names, and problem detection is performed by the investigation lead. Do not dig deeply into individual implementations
- If there is an existing investigation report, use it as an information source for understanding the mechanisms
- Also investigate the assets that may remain at the end of use. For assets in related repositories as well, list them in the same list with the repository name attached. In targets.md,
lifecycle-*For each unit of the area, enumerate data that has the identifier of that unit, and indirect assets that can be traced from it through ownership relationships or generation paths. Do not rely only on declarations of relationships. Models not connected by relationships, logs, things created in external services, and grandchild assets beyond children will be missed unless searched for from identifiers and generation paths. Distinguish originals, derivatives, evacuations, temporary storage, search indexes, caches, queues, logs and analytics replicas, external services, user devices, and backups, and list as facts up to the default handling written in code such as cascade and dependent. Do not write what actually happens in each event. The investigation lead will verify it
- Write the investigation results to
.dev/codepatrol/checklist.md:- At the beginning, record
Format、Source commit、Generated by: {Agent名 (model名)}, with {Codexの実行環境}.Source commitAs with targets.md, separate rows by repository. Make it possible to diagnose at which point and by which model the structure was understood - Summarize the mechanisms understood in the investigation as a "Security Mechanisms of This Repository" section. For libraries, write only the names without version numbers. Assets that may remain at the end of use should be placed within this section as a "Assets That May Remain at the End of Use" subsection. Mechanisms of related repositories should be placed in a "Security Mechanisms of Related Repositories" section, with a subsection for each repository
- In "Supplements to Perspectives and Unique Perspectives", write the specific names in this repository for each of the master perspectives. These are middleware names, function names, directories, etc. For perspectives on mechanisms not present in the repository, write not applicable and the reason. When there are related repositories, write so that it is clear which repository the specific names, not-applicable determinations, and unique perspectives apply to
- For perspectives on repository-specific mechanisms, in the applicable category
{カテゴリ記号}+{番号}add with. This is so that it does not get mixed up with the master's number. The report headings and the grouping when the investigation lead consults Codex reference the category symbols
- At the beginning, record
Format:
# Codepatrol Checklist ({設定を置くリポジトリ名})
Format: {現在の値}
Source commit: {設定を置くリポジトリの、読んだcommitのshort hash}
Source commit ({関連リポジトリ名}): {そのリポジトリの、読んだcommitのshort hash}
Generated by: {Agent名 (model名)}, with {Codexの実行環境}
マスターのCHECKLIST.mdと一緒に読む。ここには、設定を置くリポジトリと関連リポジトリに固有の事だけを書く。
## このリポジトリのセキュリティ機構
### {機構の区分}
### 利用終了時に残りうる資産
### 関連リポジトリのセキュリティ機構
#### {関連リポジトリ名}
## 観点への補足と固有の観点
### {カテゴリ記号}. {カテゴリ名}
- {観点番号}: {具体名。関連リポジトリがあれば、どのリポジトリの物かを添える}
- {観点番号}: 非該当。{理由}
- {カテゴリ記号}+{番号}. **{固有の観点名}**: {観点}
When updating an existing checklist.md:
Read the existing checklist.md, rescan the repository's mechanisms, and add or update mechanism facts, supplementary perspectives, and unique perspectives.
Scope of the checklist:
What to write and what not to write in the checklist follows checklist-vs-report.md . Write only specifications, mechanism explanations, and neutral perspectives. Do not write assertions about specific issues, severity, exploitation hypotheses, or references to issues in the report. If the existing checklist.md contains descriptions that do not fit this boundary, rewrite them as specification facts or neutral perspectives, or delete them.
Review of the list by codex-consultation
After generating or updating targets.md or checklist.md, review both together with codex-consultation. Even if only one was updated, pass both. This review cannot be omitted or substituted.
Skill toolで codex-consultation call.codex exec Do not settle for direct execution of. Include the following in Args:
Args: よく相談して。このリポジトリの開発チームが、自分たちのコードの問題を検出して修正するためにセキュリティ調査をしている。その調査に使う調査対象リストと観点リストを作成した。以下の2つのファイルをレビューしてほしい。
- 調査対象リスト: {.dev/codepatrol/ の絶対パス}/targets.md — 見落としているエントリポイント、領域の分け方と粒度。`lifecycle-*` の領域については、見落としている終了・縮小のイベントと入口、期待値の出典
- 観点リスト: マスター {CHECKLIST.mdの絶対パス} と、リポジトリ固有の層 {.dev/codepatrol/ の絶対パス}/checklist.md — 見落としている観点、非該当とした観点の妥当性、補った具体名の誤り。「利用終了時に残りうる資産」の節については、見落としている資産と、既定の扱いの誤り
コードの場所: {リポジトリごとの絶対パス}
When you receive feedback, read the code yourself to verify it, and reflect valid feedback in the files. Reflecting it in checklist.md follows the boundary of checklist-vs-report.md , and do not incorporate issue-leaning feedback.
Generated by In, enter your own Agent name and model name, and also record the Codex execution environment obtained by codex-consultation. When redoing only the review, keep the record of the Agent that generated it, and update only the Codex execution environment.
If Codex stops:
If Codex exits without returning a final answer due to a usage limit, spend cap, authentication error, communication failure, etc., do not substitute another means. If it is a temporary error such as a communication failure, you may wait a few minutes and retry once or twice. Usage limits and spend caps will not be resolved immediately, so do not retry.
Leave the generated files as they are, andGenerated by record "Codex review not performed" in, report what error it stopped on, and exit.
Reporting to the commander
- The generated/updated files and the commit for each repository read
- The list of areas in targets.md. In the case of an update, the areas added and the areas that no longer apply based on the scan results
- Candidate related repositories and their rationale
- Perspectives added in checklist.md, perspectives deemed not applicable, and descriptions rewritten
- Among Codex's feedback, what was reflected, what was not reflected, and the reasons
- Matters on which a judgment could not be made