openhound-edge-docs

name	openhound-edge-docs
description	Use when creating, reviewing, or improving OpenHound/BloodHound OpenGraph edge description markdown for Okta, GitHub, Jamf, or other OpenGraph extensions with Abuse Info, an optional Reverting Abuse Actions subsection, Opsec Considerations, platform-specific references, UI/API steps, and validation checks.
metadata	{"short-description":"High-quality OpenHound edge documentation"}

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:

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:

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.