feat(policies): implement workflow permissions policy evaluator

- Add GetWorkflowPermissionsAsync method to IGitHubService and GitHubService
- Implement CorrectWorkflowPermissionsEvaluator with actual policy logic
- Add WorkflowPermissionsResponse class for API deserialization
- Update documentation with new method and usage examples
- Add policy configuration example for workflow permissions
- Update CHANGELOG.md with version 0.3 release notes

This implements the security policy to ensure repositories have read-only
workflow permissions, preventing unnecessary write access in GitHub Actions.

Author: mackowski

.ai/implementation-plans/workflow-permissions-policy-evaluator.md

@@ -0,0 +1,149 @@
+# Implementation Plan: Workflow Permissions Policy Evaluator
+
+## Overview
+
+Implement the `correct_workflow_permissions` policy evaluator to check that repositories have their GitHub Actions default workflow permissions set to "read" (read repository contents and packages permissions) as specified in the PRD.
+
+## Context
+
+According to the PRD (section 3.4, policy #3), the application must verify that repositories have workflow permissions set to 'Read repository contents and packages permissions'. This is a security best practice that prevents workflows from having unnecessary write access.
+
+## Implementation Steps
+
+### 1. Add GitHub API Method for Workflow Permissions
+
+**File**: `10xGitHubPolicies.App/Services/GitHub/IGitHubService.cs`
+
+Add a new method to the interface:
+
+```csharp
+Task<string> GetWorkflowPermissionsAsync(long repositoryId);
+```
+
+**File**: `10xGitHubPolicies.App/Services/GitHub/GitHubService.cs`
+
+Implement the method using Octokit's REST API client:
+
+```csharp
+public async Task<string> GetWorkflowPermissionsAsync(long repositoryId)
+{
+    var client = await GetAuthenticatedClient();
+    try
+    {
+        // Use the GitHub API endpoint: GET /repos/{owner}/{repo}/actions/permissions/workflow
+        var connection = client.Connection;
+        var endpoint = new Uri($"repositories/{repositoryId}/actions/permissions/workflow", UriKind.Relative);
+        var response = await connection.Get<WorkflowPermissionsResponse>(endpoint, null);
+        return response.Body.DefaultWorkflowPermissions;
+    }
+    catch (NotFoundException)
+    {
+        _logger.LogWarning("Workflow permissions not found for repository {RepositoryId}. Actions may be disabled.", repositoryId);
+        return null;
+    }
+}
+
+// Add a private class for deserialization
+private class WorkflowPermissionsResponse
+{
+    public string DefaultWorkflowPermissions { get; set; }
+    public bool CanApprovePullRequestReviews { get; set; }
+}
+```
+
+### 2. Implement the Policy Evaluator Logic
+
+**File**: `10xGitHubPolicies.App/Services/Policies/Evaluators/CorrectWorkflowPermissionsEvaluator.cs`
+
+Replace the TODO implementation with actual logic:
+
+```csharp
+public async Task<PolicyViolation?> EvaluateAsync(Octokit.Repository repository)
+{
+    var permissions = await _githubService.GetWorkflowPermissionsAsync(repository.Id);
+    
+    // If permissions is null, Actions might be disabled - consider this compliant
+    if (permissions == null)
+    {
+        return null;
+    }
+    
+    // Check if permissions are set to "read" (the secure, restrictive setting)
+    if (permissions != "read")
+    {
+        return new PolicyViolation
+        {
+            PolicyType = PolicyType
+        };
+    }
+    
+    return null;
+}
+```
+
+### 3. Update Documentation
+
+**File**: `docs/github-integration.md`
+
+Add the new method to the IGitHubService methods list (around line 16):
+
+```markdown
+- `Task<string> GetWorkflowPermissionsAsync(long repositoryId)`: Gets the default workflow permissions for a repository. Returns "read" or "write", or null if Actions are disabled.
+```
+
+Add a usage example in the document:
+
+````markdown
+### Example: Checking Workflow Permissions
+
+```csharp
+public async Task CheckRepositorySecurityAsync(long repositoryId)
+{
+    var permissions = await _gitHubService.GetWorkflowPermissionsAsync(repositoryId);
+    
+    if (permissions == "write")
+    {
+        _logger.LogWarning("Repository {RepoId} has write permissions for workflows", repositoryId);
+    }
+}
+````
+
+```
+
+**File**: `docs/policy-evaluation.md`
+
+Update the example configuration (around line 119) to include a complete example for the workflow permissions policy:
+
+```yaml
+- name: 'Verify Workflow Permissions'
+  type: 'correct_workflow_permissions'
+  action: 'create-issue'
+  issue_details:
+    title: 'Security: Workflow permissions should be read-only'
+    body: 'This repository has GitHub Actions workflow permissions set to write. For security, please change the default workflow permissions to "Read repository contents and packages permissions" in Settings > Actions > General.'
+    labels: ['policy-violation', 'security']
+```
+
+## Key Technical Details
+
+- **GitHub API Endpoint**: `GET /repos/{owner}/{repo}/actions/permissions/workflow`
+- **Expected Values**: 
+  - `"read"` - Read-only permissions (compliant)
+  - `"write"` - Read and write permissions (violation)
+  - `null` - Actions disabled or permissions not configured (treated as compliant)
+- **Octokit Usage**: Uses the low-level `Connection.Get<T>()` method since Octokit.net may not have a high-level wrapper for this endpoint
+- **Error Handling**: Returns null for NotFoundException, treating disabled Actions as compliant
+
+## Testing Considerations
+
+After implementation, test with:
+
+1. A repository with read-only workflow permissions (should pass)
+2. A repository with write workflow permissions (should fail)
+3. A repository with Actions disabled (should pass)
+
+## Dependencies
+
+- Existing `IGitHubService` infrastructure
+- Octokit.net library (already installed)
+- Entity Framework entities (PolicyViolation)

10xGitHubPolicies.App/Services/GitHub/GitHubService.cs

@@ -116,6 +116,24 @@ public async Task<string> GetFileContentAsync(string repoName, string path)
         }
     }
 
+    public async Task<string> GetWorkflowPermissionsAsync(long repositoryId)
+    {
+        var client = await GetAuthenticatedClient();
+        try
+        {
+            // Use the GitHub API endpoint: GET /repos/{owner}/{repo}/actions/permissions/workflow
+            var connection = client.Connection;
+            var endpoint = new Uri($"repositories/{repositoryId}/actions/permissions/workflow", UriKind.Relative);
+            var response = await connection.Get<WorkflowPermissionsResponse>(endpoint, null);
+            return response.Body.DefaultWorkflowPermissions;
+        }
+        catch (NotFoundException)
+        {
+            _logger.LogWarning("Workflow permissions not found for repository {RepositoryId}. Actions may be disabled.", repositoryId);
+            return null;
+        }
+    }
+
     private async Task<GitHubClient> GetAuthenticatedClient()
     {
         var token = await _cache.GetOrCreateAsync(InstallationTokenCacheKey, async entry =>
@@ -154,4 +172,11 @@ private string GetJwt()
         var token = tokenHandler.CreateToken(tokenDescriptor);
         return tokenHandler.WriteToken(token);
     }
+}
+
+// Add a private class for deserialization
+public class WorkflowPermissionsResponse
+{
+    public string DefaultWorkflowPermissions { get; set; }
+    public bool CanApprovePullRequestReviews { get; set; }
 }

10xGitHubPolicies.App/Services/GitHub/IGitHubService.cs

@@ -14,4 +14,5 @@ public interface IGitHubService
     Task ArchiveRepositoryAsync(long repositoryId);
     Task<bool> IsUserMemberOfTeamAsync(string userAccessToken, string org, string teamSlug);
     Task<string> GetFileContentAsync(string repoName, string path);
+    Task<string> GetWorkflowPermissionsAsync(long repositoryId);
 }

10xGitHubPolicies.App/Services/Policies/Evaluators/CorrectWorkflowPermissionsEvaluator.cs

@@ -16,10 +16,23 @@ public CorrectWorkflowPermissionsEvaluator(IGitHubService githubService)
 
     public async Task<PolicyViolation?> EvaluateAsync(Octokit.Repository repository)
     {
-        // TODO: Implement the logic to check workflow permissions.
-        // This will likely require a new method in IGitHubService to get repository actions settings.
-        // For now, we'll assume it's always compliant.
-        await Task.CompletedTask;
+        var permissions = await _githubService.GetWorkflowPermissionsAsync(repository.Id);
+        
+        // If permissions is null, Actions might be disabled - consider this compliant
+        if (permissions == null)
+        {
+            return null;
+        }
+        
+        // Check if permissions are set to "read" (the secure, restrictive setting)
+        if (permissions != "read")
+        {
+            return new PolicyViolation
+            {
+                PolicyType = PolicyType
+            };
+        }
+        
         return null;
     }
 }

CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.3
+
+### Added
+- **Workflow Permissions Policy Evaluator**: Implemented `CorrectWorkflowPermissionsEvaluator` to enforce security best practices for GitHub Actions workflow permissions.
+  - Added `GetWorkflowPermissionsAsync()` method to `IGitHubService` and `GitHubService` to retrieve repository workflow permissions via GitHub API
+  - Added `WorkflowPermissionsResponse` class for API response deserialization
+  - Policy checks that repositories have read-only workflow permissions (security compliance)
+  - Handles cases where GitHub Actions are disabled (treated as compliant)
+- **Enhanced GitHub Integration**: Extended GitHub service with workflow permissions API integration
+  - Uses GitHub API endpoint `GET /repos/{owner}/{repo}/actions/permissions/workflow`
+  - Proper error handling for repositories with disabled Actions
+  - Returns "read", "write", or null for disabled Actions
+- **Documentation Updates**: 
+  - Updated `docs/github-integration.md` with new `GetWorkflowPermissionsAsync` method documentation and usage examples
+  - Updated `docs/policy-evaluation.md` with complete workflow permissions policy configuration example
+  - Added policy violation issue template for workflow permissions violations
+
+### Changed
+- **Policy Evaluation**: `CorrectWorkflowPermissionsEvaluator` now implements actual policy logic instead of placeholder TODO
+- **Security Enhancement**: Enforces that repositories must have read-only workflow permissions to prevent unnecessary write access in GitHub Actions
+
+### Dependencies
+- No new dependencies added (uses existing Octokit.net library)
+
+---
+
 ## 0.2
 
 ### Changed

docs/github-integration.md

@@ -14,6 +14,7 @@ This document outlines the approach to integrating with the GitHub API using the
     - `Task ArchiveRepositoryAsync(long repositoryId)`: Archives a repository.
     - `Task<bool> IsUserMemberOfTeamAsync(string userAccessToken, string org, string teamSlug)`: Verifies if a user is a member of a specific GitHub team (used for access control).
     - `Task<string> GetFileContentAsync(string repoName, string path)`: Retrieves file content from a repository. Returns Base64-encoded content or `null` if the file doesn't exist.
+    - `Task<string> GetWorkflowPermissionsAsync(long repositoryId)`: Gets the default workflow permissions for a repository. Returns "read" or "write", or null if Actions are disabled.
 
 ### `GitHubService`
 - **Purpose**: Implements `IGitHubService` and handles the authentication and caching of the GitHub App installation token.
@@ -141,6 +142,20 @@ public class AccessControlService
 }
 ```
 
+### Example: Checking Workflow Permissions
+
+```csharp
+public async Task CheckRepositorySecurityAsync(long repositoryId)
+{
+    var permissions = await _gitHubService.GetWorkflowPermissionsAsync(repositoryId);
+    
+    if (permissions == "write")
+    {
+        _logger.LogWarning("Repository {RepoId} has write permissions for workflows", repositoryId);
+    }
+}
+```
+
 ## Best Practices
 
 1. **Use Dependency Injection**: Always inject `IGitHubService` rather than creating instances directly.

docs/policy-evaluation.md

@@ -122,6 +122,15 @@ policies:
       title: 'Compliance: Your new policy violation'
       body: 'Details about why this is a violation.'
       labels: ['policy-violation', 'your-label']
+
+  # Example: Workflow Permissions Policy
+  - name: 'Verify Workflow Permissions'
+    type: 'correct_workflow_permissions'
+    action: 'create-issue'
+    issue_details:
+      title: 'Security: Workflow permissions should be read-only'
+      body: 'This repository has GitHub Actions workflow permissions set to write. For security, please change the default workflow permissions to "Read repository contents and packages permissions" in Settings > Actions > General.'
+      labels: ['policy-violation', 'security']
 ```
 
 Once these steps are completed, the `ScanningService` will automatically pick up and execute your new policy evaluator during the next scan.