openhound-edge-docs

# OpenHound Edge Docs Use this skill when editing `descriptions/edges/*.md` files for an OpenHound extension. This skill is distributed with `og-docs-automation` under `skills/openhound-edge-docs`. Install it into Codex with: ```bash pwsh docs/og-docs-automation/scripts/Install-CodexSkill.ps1 ``` ## Workflow 1. Inspect the target edge docs, `extension/schema.json`, and the collector/model code that emits the edge. 2. Classify each edge into a family from `references/edge-family-playbooks.md`. 3. Use `references/edge-doc-template.md` as the required quality bar. 4. Detect the platform from schema metadata, node/edge prefixes, repository name, and collector code. Load exactly one matching platform profile when available: - Okta: `references/platforms/okta.md` - GitHub: `references/platforms/github.md` - Jamf: `references/platforms/jamf.md` - Unknown or new platform: `references/platforms/generic.md` 5. Verify current API, UI, and event/log details against official vendor docs before adding endpoint names, UI labels, event types, or command examples. Use platform profiles for source selection and conventions. 6. Add or update: - `## Abuse Info` - `## Opsec Considerations` - `## References` 7. Add `### Reverting Abuse Actions` inside `## Abuse Info` only when the documented abuse procedure changes the environment or leaves test-created artifacts, persistence, or reusable access that must be removed. Omit the subsection entirely when there is nothing to reverse. 8. Make content edge-specific. Avoid generic sentences that could be pasted into any edge. 9. Prefer exact UI/Admin Console steps and API/CLI steps. If an edge crosses into another platform, IdP, MDM, cloud, CI/CD, SaaS, endpoint, or directory, say which source-system API or console must be used and what to verify. 10. Do not invent endpoints, event names, console labels, permissions, or capabilities. If uncertain, use official-doc wording and state the dependency. 11. Match the quality bar for the current platform: - API sections must include runnable fenced code blocks where an API can perform or verify the action. - Start examples with exported variables for the platform base URL, token, IDs, and controlled values. - Include the action request, expected success signal, and at least one verification request. - Use the platform profile's authentication/header style. - When the optional reversal subsection is present, its API steps must include concrete restoration and verification blocks. - If the action must happen in another source system and no platform API can do it, provide a source-system command/API placeholder plus platform API calls that verify or reverse test-created effects on the platform side. - References must use markdown link syntax (`- [Title](URL)`) and prefer operation-specific official docs before research references. 12. Validate from the repo root: ```bash python3 docs/og-docs-automation/skills/openhound-edge-docs/scripts/audit_edge_docs.py descriptions/edges git diff --check pwsh docs/og-docs-automation/scripts/Test-SchemaConsistency.ps1 ``` ## Platform Detection Use this order: 1. `extension/schema.json` metadata such as `namespace`, `source_kind`, `environment_kind`, or display/name fields. 2. Edge filename prefixes: `Okta_`, `GH_`, `jamf_`, or other extension-specific prefixes. 3. Collector package/module names and repository names. 4. Existing docs under `descriptions/nodes`, `descriptions/edges`, and `docs/graph`. If several platforms are involved, load the source platform profile plus any downstream platform profile needed to reverse abuse actions or verify restoration. ## Optional Reverting Abuse Actions Subsection Add `### Reverting Abuse Actions` within `## Abuse Info` only when the documented abuse procedure changes the environment or leaves test-created artifacts, persistence, or reusable access that the red teamer or penetration tester must remove. Recommend how to undo those actions and restore the recorded pre-abuse state. Omit the subsection when the abuse only traverses or uses a pre-existing relationship without changing the environment. For example, omit it for a `MemberOf` edge when the abuse only relies on an existing group membership. Do not add a subsection merely to say that no reversal is required. Ordinary sign-in or audit events caused by using an existing relationship do not by themselves justify the subsection. Apply these boundaries: - Identify the delta between the recorded pre-abuse state and the post-abuse state. Reverse that delta; do not remediate the pre-existing relationship represented by the edge. - Preserve permissions, memberships, configuration, credentials, and other state that existed before the test unless the abuse modified or exposed them. - Remove attacker-created access and persistence such as added principals, role or group assignments, access-control entries, policies, keys, tokens, sessions, applications, scripts, workflows, branches, webhooks, or device profiles. - Restore values overwritten during abuse to their exact previous values. Do not substitute a hardened value or redesign the configuration as part of this section. - Revoke or rotate credentials and sessions created or exposed by the abuse when leaving them valid would create risk. Do not revoke a pre-existing credential merely because it enabled the edge. - Include downstream and cross-platform effects caused by the abuse, not unrelated hardening recommendations. - If the abuse makes no change and leaves no test-created artifact, persistence, or reusable access, omit the subsection. Keep remediation or mitigation of the edge outside this section. For example, if a principal has a pre-existing Active Directory `WriteDACL` right and the tester abuses it by adding a `GenericAll` ACE, instruct the tester to remove only the ACE added during the test and verify that the original DACL is restored. Do not instruct them to remove or modify the pre-existing `WriteDACL` right. ## Quality Rules - Every edge needs references. Use official vendor docs first. - References should use short markdown link titles, operation-specific official docs first, then research/tool links only when they add edge-specific value. - Non-direct edges still need a path: explain how control of the source can compromise, influence, or help compromise the destination. - When present, the reversal subsection must name the exact test-created or test-modified state being restored before listing steps. - When present, reversal steps must include UI/Admin Console and API/CLI guidance when possible. - Omit the reversal subsection when the abuse does not change the environment, including paths that only use a pre-existing `MemberOf` relationship. - Never present removal of the pre-existing edge relationship as reversal of abuse unless the test itself created or changed that relationship. - API examples must include code blocks for setup, action, and verification when the target platform exposes an API. - Opsec should name specific log sources and event types when known. - Keep the docs useful for operators and defenders; avoid filler. ## Okta Compatibility For state-changing Okta edges, keep using `Okta_AddMember.md` as the minimum quality bar: concrete abuse path, concrete optional reversal subsection, runnable Okta API code blocks, verification, opsec, and markdown-link references. Omit the reversal subsection from Okta edges whose abuse changes no state. The full Okta-specific source and API guidance lives in `references/platforms/okta.md`.