A Go library and CLI for building custom GitHub slash commands.

• Library: Build custom slash commands using the octoslash Go library
• Built-in Commands: Ready-to-use commands for common GitHub operations
• CLI tool: Standalone binary with built-in commands for immediate use
• GitHub Action: Easy integration via sagikazarmark/octoslash-action
• Authorization: Fine-grained access control using Cedar policies

Check out this repository for a quickstart guide.

See sagikazarmark/octoslash-action.

Download the latest release from the releases page or install using Go:

go install github.com/sagikazarmark/octoslash/cmd/octoslash@latest

Add octoslash to your Go project:

go get github.com/sagikazarmark/octoslash

Check out this page for a list of built-in commands.

The octoslash binary uses the Cedar policy language for fine-grained authorization. By default, all commands are denied unless explicitly allowed by a policy.

The library allows alternative authorization mechanisms by implementing the appropriate interface.

Create authorization configuration in .github/octoslash/:

.github/octoslash/
├── principals.json         # User and role mappings
└── policies/
    ├── collaborator.cedar  # Policies for collaborators
    └── triager.cedar       # Policies for triagers

Map GitHub users to roles in principals.json:

[
    {
        "uid": { "type": "User", "id": "1226384" },
        "attrs": { "login": "sagikazarmark" },
        "parents": [{ "type": "Role", "id": "Collaborator" }]
    },
    {
        "uid": { "type": "User", "id": "987654321" },
        "attrs": { "login": "triager" },
        "parents": [{ "type": "Role", "id": "Triager" }]
    }
]

Collaborator Policy (policies/collaborator.cedar):

// Collaborators can perform all actions
permit(
    principal in Role::"Collaborator",
    action,
    resource
);

Triager Policy (policies/triager.cedar):

// Triagers can only close, label, and remove labels on issues (not PRs)
permit(
    principal in Role::"Triager",
    action in [Action::"Close", Action::"Label", Action::"RemoveLabel"],
    resource is Issue
);

TODO

Octoslash implements several security measures to protect against common attack vectors:

• Risk: Malicious users executing privileged commands
• Mitigation: Authorization with deny-by-default policy
• Protection: All commands require explicit policy permissions

• Risk: Malicious PRs modifying GitHub Action workflows or policies
• Mitigation: GitHub workflows for issue_comment events only run on the default branch
• Protection: Malicious actors cannot gain privileges by submitting malicious PRs

• Risk: Malicious command arguments causing unintended behavior
• Mitigation: Structured command parsing using mvdan/sh
• Protection: Argument validation and type safety

1. Use minimal GitHub token permissions:

   permissions:
     issues: write
     # Disable (or rather don't enable) unnecessary permissions
     # pull-requests: write

2. Implement granular Cedar policies:

   // Prefer specific permissions over broad access
   permit(
     principal in Role::"Triager",
     action == Action::"Label",
     resource is Issue
   );
   

3. Regular policy audits: Review and update authorization policies regularly

TODO

The project is licensed under the MIT License.