Building 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company đŸ‘‡
Go aicertificationcloud-engineeringcybercybersecuritycybersecurity-analystcybersecurity-certificationcybersecurity-certificationscybersecurity-educationcybersecurity-jobscybersecurity-portfoliocybersecurity-projectscybersecurity-toolsgrchackinglearningpentestingproject-repositoryprojetcspython
feat(rotators): GitHub fine-grained PAT rotator + thin GitHub API client
CarterPerez-dev873257ad4b70
diff --git a/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/github/client_spec.cr b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/github/client_spec.crnew file mode 100644index 00000000..c5511049--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/github/client_spec.cr@@ -0,0 +1,51 @@+# ===================+# ©AngelaMos | 2026+# client_spec.cr+# ===================++require "../../spec_helper"+require "webmock"+require "../../../src/cre/github/client"++WebMock.allow_net_connect = false++private def fresh_client+ CRE::Github::Client.new(token: "ghp_admin")+end++describe CRE::Github::Client do+ before_each { WebMock.reset }++ it "creates a fine-grained PAT" do+ WebMock.stub(:post, "https://api.github.com/user/personal-access-tokens")+ .with(headers: {"Authorization" => "Bearer ghp_admin"})+ .to_return(body: %({"id":12345,"token":"ghp_newvalue","expires_at":"2026-07-01T00:00:00Z"}))++ token = fresh_client.create_pat("my-pat", ["repo", "read:org"], 90)+ token.id.should eq 12345_i64+ token.token_value.should eq "ghp_newvalue"+ token.expires_at.should eq "2026-07-01T00:00:00Z"+ end++ it "deletes a PAT" do+ deleted = false+ WebMock.stub(:delete, "https://api.github.com/user/personal-access-tokens/12345")+ .with(headers: {"Authorization" => "Bearer ghp_admin"})+ .to_return { |_| deleted = true; HTTP::Client::Response.new(200, body: "{}") }+ fresh_client.delete_pat(12345_i64)+ deleted.should be_true+ end++ it "fetches the authenticated user" do+ WebMock.stub(:get, "https://api.github.com/user")+ .to_return(body: %({"login":"octocat","id":1}))+ user = fresh_client.me+ user["login"].as_s.should eq "octocat"+ end++ it "raises GithubError on non-2xx" do+ WebMock.stub(:get, "https://api.github.com/user")+ .to_return(status: 401, body: %({"message":"Bad credentials"}))+ expect_raises(CRE::Github::GithubError) { fresh_client.me }+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/rotators/github_pat_spec.cr b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/rotators/github_pat_spec.crnew file mode 100644index 00000000..214d0288--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/rotators/github_pat_spec.cr@@ -0,0 +1,87 @@+# ===================+# ©AngelaMos | 2026+# github_pat_spec.cr+# ===================++require "../../spec_helper"+require "webmock"+require "../../../src/cre/rotators/github_pat"++WebMock.allow_net_connect = false++private def github_credential(old_pat_id : String = "111")+ CRE::Domain::Credential.new(+ id: UUID.random,+ external_id: "deploy-bot",+ kind: CRE::Domain::CredentialKind::GithubPat,+ name: "deploy-bot",+ tags: {+ "name" => "deploy-bot",+ "scopes" => %(["repo","read:org"]),+ "old_pat_id" => old_pat_id,+ "expires_in_days" => "90",+ } of String => String,+ )+end++private def gh_client+ CRE::Github::Client.new(token: "ghp_admin")+end++describe CRE::Rotators::GithubPatRotator do+ before_each { WebMock.reset }++ it "executes the full 4-step contract" do+ cred = github_credential++ WebMock.stub(:post, "https://api.github.com/user/personal-access-tokens")+ .to_return(body: %({"id":99999,"token":"ghp_new","expires_at":"2026-07-01T00:00:00Z"}))++ rotator = CRE::Rotators::GithubPatRotator.new(gh_client)+ rotator.can_rotate?(cred).should be_true++ new_secret = rotator.generate(cred)+ new_secret.metadata["new_pat_id"].should eq "99999"+ new_secret.metadata["old_pat_id"].should eq "111"+ String.new(new_secret.ciphertext).should eq "ghp_new"++ rotator.apply(cred, new_secret) # no-op++ WebMock.stub(:get, "https://api.github.com/user")+ .with(headers: {"Authorization" => "Bearer ghp_new"})+ .to_return(body: %({"login":"deploy-bot"}))+ rotator.verify(cred, new_secret).should be_true++ deleted_old = false+ WebMock.stub(:delete, "https://api.github.com/user/personal-access-tokens/111")+ .to_return { |_| deleted_old = true; HTTP::Client::Response.new(200, body: "{}") }+ rotator.commit(cred, new_secret)+ deleted_old.should be_true+ end++ it "verify returns false when /user fails with new token" do+ cred = github_credential+ WebMock.stub(:get, "https://api.github.com/user")+ .to_return(status: 401, body: %({"message":"bad"}))+ rotator = CRE::Rotators::GithubPatRotator.new(gh_client)+ s = CRE::Domain::NewSecret.new(+ ciphertext: "ghp_bad".to_slice,+ metadata: {"new_pat_id" => "1", "old_pat_id" => "0"},+ )+ rotator.verify(cred, s).should be_false+ end++ it "rollback_apply deletes the new PAT" do+ cred = github_credential+ rotator = CRE::Rotators::GithubPatRotator.new(gh_client)+ s = CRE::Domain::NewSecret.new(+ ciphertext: "ghp_new".to_slice,+ metadata: {"new_pat_id" => "888"},+ )+ deleted = false+ WebMock.stub(:delete, "https://api.github.com/user/personal-access-tokens/888")+ .to_return { |_| deleted = true; HTTP::Client::Response.new(200, body: "{}") }+ rotator.rollback_apply(cred, s)+ deleted.should be_true+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/github/client.cr b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/github/client.crnew file mode 100644index 00000000..f4f1baa8--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/github/client.cr@@ -0,0 +1,82 @@+# ===================+# ©AngelaMos | 2026+# client.cr+# ===================++require "http/client"+require "json"++module CRE::Github+ class GithubError < Exception+ getter status : Int32++ def initialize(message : String, @status : Int32)+ super(message)+ end+ end++ # Thin GitHub REST client. We target fine-grained PATs for rotation since the+ # /user/personal-access-tokens endpoint accepts programmatic creation /+ # deletion when the bearer token has the appropriate Apps-managed permission.+ # For the test/portfolio path we mock these endpoints directly.+ class Client+ record Token, id : Int64, token_value : String, expires_at : String?++ DEFAULT_API = "https://api.github.com"++ def initialize(@token : String, @api_base : String = DEFAULT_API)+ end++ def me : JSON::Any+ get("/user")+ end++ def create_pat(name : String, scopes : Array(String), expires_in_days : Int32 = 90) : Token+ payload = {+ "name" => name,+ "expires_in_days" => expires_in_days,+ "scopes" => scopes,+ }.to_json+ json = post("/user/personal-access-tokens", payload)+ Token.new(+ id: json["id"].as_i64,+ token_value: json["token"].as_s,+ expires_at: json["expires_at"]?.try(&.as_s),+ )+ end++ def delete_pat(token_id : Int64) : Nil+ delete("/user/personal-access-tokens/#{token_id}")+ end++ private def get(path : String) : JSON::Any+ response = HTTP::Client.get(url(path), headers: headers)+ raise GithubError.new("GET #{path}: #{response.body[0, 200]?}", response.status_code) unless response.status_code < 300+ JSON.parse(response.body)+ end++ private def post(path : String, body : String) : JSON::Any+ response = HTTP::Client.post(url(path), headers: headers, body: body)+ raise GithubError.new("POST #{path}: #{response.body[0, 200]?}", response.status_code) unless response.status_code < 300+ JSON.parse(response.body)+ end++ private def delete(path : String) : Nil+ response = HTTP::Client.delete(url(path), headers: headers)+ raise GithubError.new("DELETE #{path}: #{response.body[0, 200]?}", response.status_code) unless response.status_code < 300+ end++ private def headers : HTTP::Headers+ HTTP::Headers{+ "Authorization" => "Bearer #{@token}",+ "Accept" => "application/vnd.github+json",+ "X-GitHub-Api-Version" => "2022-11-28",+ "Content-Type" => "application/json",+ }+ end++ private def url(path : String) : String+ "#{@api_base}#{path}"+ end+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/rotators/github_pat.cr b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/rotators/github_pat.crnew file mode 100644index 00000000..85e353fa--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/rotators/github_pat.cr@@ -0,0 +1,78 @@+# ===================+# ©AngelaMos | 2026+# github_pat.cr+# ===================++require "json"+require "../github/client"+require "./rotator"++module CRE::Rotators+ # GithubPatRotator manages fine-grained Personal Access Tokens. It uses an+ # admin/issuer bearer to create the new PAT and to delete the old one.+ #+ # Required Credential.tags:+ # "name" - PAT label+ # "old_pat_id" - the GitHub PAT id to revoke on commit+ # "scopes" - JSON-encoded array of scope strings (e.g. ["repo","read:org"])+ # Optional "expires_in_days" - default 90+ class GithubPatRotator < Rotator+ register_as :github_pat++ def initialize(@client : Github::Client)+ end++ def kind : Symbol+ :github_pat+ end++ def can_rotate?(c : Domain::Credential) : Bool+ c.kind.github_pat? && !c.tag("name").nil? && !c.tag("scopes").nil?+ end++ def generate(c : Domain::Credential) : Domain::NewSecret+ raise RotatorError.new("missing 'name' or 'scopes' tag") unless can_rotate?(c)+ scopes = Array(String).from_json(c.tag("scopes").not_nil!)+ expires_in_days = (c.tag("expires_in_days") || "90").to_i++ new_token = @client.create_pat(c.tag("name").not_nil!, scopes, expires_in_days)++ Domain::NewSecret.new(+ ciphertext: new_token.token_value.to_slice,+ metadata: {+ "new_pat_id" => new_token.id.to_s,+ "old_pat_id" => c.tag("old_pat_id") || "",+ "expires_at" => new_token.expires_at || "",+ },+ )+ end++ def apply(c : Domain::Credential, s : Domain::NewSecret) : Nil+ _ = {c, s}+ # No-op: create_pat already exposed the token. Old PAT still works.+ end++ def verify(c : Domain::Credential, s : Domain::NewSecret) : Bool+ _ = c+ probe = Github::Client.new(String.new(s.ciphertext))+ probe.me+ true+ rescue+ false+ end++ def commit(c : Domain::Credential, s : Domain::NewSecret) : Nil+ _ = c+ old = s.metadata["old_pat_id"]?+ return if old.nil? || old.empty?+ @client.delete_pat(old.to_i64)+ end++ def rollback_apply(c : Domain::Credential, s : Domain::NewSecret) : Nil+ _ = c+ new_id = s.metadata["new_pat_id"]?+ return if new_id.nil? || new_id.empty?+ @client.delete_pat(new_id.to_i64) rescue nil+ end+ end+end