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): abstract Rotator with macro registration + EnvFileRotator + 4-step orchestrator
CarterPerez-devbad50daad294
diff --git a/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/rotation_orchestrator_spec.cr b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/rotation_orchestrator_spec.crnew file mode 100644index 00000000..6b98dd1c--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/rotation_orchestrator_spec.cr@@ -0,0 +1,131 @@+# ===================+# ©AngelaMos | 2026+# rotation_orchestrator_spec.cr+# ===================++require "../../spec_helper"+require "../../../src/cre/engine/rotation_orchestrator"+require "../../../src/cre/persistence/sqlite/sqlite_persistence"+require "../../../src/cre/rotators/env_file"++private def drain(ch : ::Channel(CRE::Events::Event)) : Array(CRE::Events::Event)+ out = [] of CRE::Events::Event+ loop do+ select+ when ev = ch.receive+ out << ev+ else+ break+ end+ end+ out+end++private def env_credential(path : String, key : String) : CRE::Domain::Credential+ CRE::Domain::Credential.new(+ id: UUID.random,+ external_id: "#{path}::#{key}",+ kind: CRE::Domain::CredentialKind::EnvFile,+ name: key,+ tags: {"path" => path, "key" => key} of String => String,+ )+end++describe CRE::Engine::RotationOrchestrator do+ it "publishes the full event sequence on success" do+ tmp = File.tempfile("cre_rot_") { |f| f << "K=v\n" }+ cred = env_credential(tmp.path, "K")++ persist = CRE::Persistence::Sqlite::SqlitePersistence.new(":memory:")+ persist.migrate!+ persist.credentials.insert(cred)++ bus = CRE::Engine::EventBus.new+ ch = bus.subscribe+ bus.run++ orchestrator = CRE::Engine::RotationOrchestrator.new(bus, persist)+ state = orchestrator.run(cred, CRE::Rotators::EnvFileRotator.new)++ sleep 0.1.seconds+ state.completed?.should be_true++ events = drain(ch).map(&.class.name)+ events.should contain "CRE::Events::RotationStarted"+ events.count("CRE::Events::RotationStepCompleted").should eq 4+ events.should contain "CRE::Events::RotationCompleted"+ events.should_not contain "CRE::Events::RotationFailed"++ # rotation row recorded as completed+ persist.rotations.in_flight.size.should eq 0+ ensure+ bus.try(&.stop)+ persist.try(&.close)+ tmp.try(&.delete)+ end++ it "handles a rotator that raises during apply via rollback" do+ tmp = File.tempfile("cre_rot_fail_") { |f| f << "K=v\n" }+ cred = env_credential(tmp.path, "K")++ persist = CRE::Persistence::Sqlite::SqlitePersistence.new(":memory:")+ persist.migrate!+ persist.credentials.insert(cred)++ bus = CRE::Engine::EventBus.new+ ch = bus.subscribe+ bus.run++ failing = FailingRotator.new+ state = CRE::Engine::RotationOrchestrator.new(bus, persist).run(cred, failing)+ sleep 0.1.seconds++ state.failed?.should be_true+ failing.rolled_back.should be_true++ events = drain(ch).map(&.class.name)+ events.should contain "CRE::Events::RotationStepFailed"+ events.should contain "CRE::Events::RotationFailed"+ ensure+ bus.try(&.stop)+ persist.try(&.close)+ tmp.try(&.delete)+ end+end++class FailingRotator < CRE::Rotators::Rotator+ property rolled_back = false++ def kind : Symbol+ :env_file+ end++ def can_rotate?(c : CRE::Domain::Credential) : Bool+ _ = c+ true+ end++ def generate(c : CRE::Domain::Credential) : CRE::Domain::NewSecret+ _ = c+ CRE::Domain::NewSecret.new(ciphertext: "x".to_slice)+ end++ def apply(c : CRE::Domain::Credential, s : CRE::Domain::NewSecret) : Nil+ _ = {c, s}+ raise CRE::Rotators::RotatorError.new("apply boom")+ end++ def verify(c : CRE::Domain::Credential, s : CRE::Domain::NewSecret) : Bool+ _ = {c, s}+ true+ end++ def commit(c : CRE::Domain::Credential, s : CRE::Domain::NewSecret) : Nil+ _ = {c, s}+ end++ def rollback_apply(c : CRE::Domain::Credential, s : CRE::Domain::NewSecret) : Nil+ _ = {c, s}+ @rolled_back = true+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/rotators/env_file_spec.cr b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/rotators/env_file_spec.crnew file mode 100644index 00000000..5b286a98--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/rotators/env_file_spec.cr@@ -0,0 +1,91 @@+# ===================+# ©AngelaMos | 2026+# env_file_spec.cr+# ===================++require "../../spec_helper"+require "../../../src/cre/rotators/env_file"++private def credential_for(path : String, key : String, bytes : Int32 = 32)+ CRE::Domain::Credential.new(+ id: UUID.random,+ external_id: "#{path}::#{key}",+ kind: CRE::Domain::CredentialKind::EnvFile,+ name: key,+ tags: {"path" => path, "key" => key, "bytes" => bytes.to_s} of String => String,+ )+end++describe CRE::Rotators::EnvFileRotator do+ it "executes the full 4-step contract" do+ tmp = File.tempfile("cre_env_test_") do |f|+ f << "API_KEY=oldvalue\nOTHER=keep\n"+ end+ path = tmp.path+ cred = credential_for(path, "API_KEY")+ rotator = CRE::Rotators::EnvFileRotator.new++ rotator.can_rotate?(cred).should be_true++ new_secret = rotator.generate(cred)+ new_secret.metadata["key"].should eq "API_KEY"+ new_secret.ciphertext.size.should be > 0++ rotator.apply(cred, new_secret)+ File.exists?("#{path}.pending").should be_true+ rotator.verify(cred, new_secret).should be_true++ rotator.commit(cred, new_secret)+ File.exists?("#{path}.pending").should be_false++ final = File.read(path)+ new_value = String.new(new_secret.ciphertext)+ final.includes?("API_KEY=#{new_value}").should be_true+ final.includes?("OTHER=keep").should be_true+ final.includes?("API_KEY=oldvalue").should be_false+ ensure+ tmp.try(&.delete)+ end++ it "rollback_apply removes the pending file" do+ tmp = File.tempfile("cre_env_rb_") do |f|+ f << "K=v\n"+ end+ cred = credential_for(tmp.path, "K")+ rotator = CRE::Rotators::EnvFileRotator.new++ s = rotator.generate(cred)+ rotator.apply(cred, s)+ File.exists?("#{tmp.path}.pending").should be_true++ rotator.rollback_apply(cred, s)+ File.exists?("#{tmp.path}.pending").should be_false+ File.read(tmp.path).should eq "K=v\n"+ ensure+ tmp.try(&.delete)+ end++ it "can_rotate? returns false without required tags" do+ bad_cred = CRE::Domain::Credential.new(+ id: UUID.random, external_id: "x",+ kind: CRE::Domain::CredentialKind::EnvFile,+ name: "x", tags: {} of String => String,+ )+ CRE::Rotators::EnvFileRotator.new.can_rotate?(bad_cred).should be_false+ end++ it "creates the file if missing" do+ path = File.tempname("cre_env_new_", ".env")+ cred = credential_for(path, "FRESH")+ rotator = CRE::Rotators::EnvFileRotator.new++ s = rotator.generate(cred)+ rotator.apply(cred, s)+ rotator.verify(cred, s).should be_true+ rotator.commit(cred, s)+ File.exists?(path).should be_true+ File.read(path).includes?("FRESH=").should be_true+ ensure+ File.delete(path) if path && File.exists?(path)+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/rotators/rotator_spec.cr b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/rotators/rotator_spec.crnew file mode 100644index 00000000..897abb63--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/rotators/rotator_spec.cr@@ -0,0 +1,20 @@+# ===================+# ©AngelaMos | 2026+# rotator_spec.cr+# ===================++require "../../spec_helper"+require "../../../src/cre/rotators/rotator"+require "../../../src/cre/rotators/env_file"++describe CRE::Rotators::Rotator do+ it "registers concrete rotator subclasses via register_as macro" do+ CRE::Rotators::Rotator::REGISTRY[:env_file]?.should_not be_nil+ CRE::Rotators::Rotator.for(:env_file).should eq CRE::Rotators::EnvFileRotator+ CRE::Rotators::Rotator.registered_kinds.should contain(:env_file)+ end++ it "for returns nil for unknown kinds" do+ CRE::Rotators::Rotator.for(:nonexistent).should be_nil+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/rotation_orchestrator.cr b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/rotation_orchestrator.crnew file mode 100644index 00000000..899315e8--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/rotation_orchestrator.cr@@ -0,0 +1,93 @@+# ===================+# ©AngelaMos | 2026+# rotation_orchestrator.cr+# ===================++require "log"+require "uuid"+require "./event_bus"+require "../events/credential_events"+require "../rotators/rotator"+require "../persistence/persistence"+require "../persistence/repos"++module CRE::Engine+ class VerifyFailed < Exception; end++ class RotationOrchestrator+ Log = ::Log.for("cre.rotator")++ def initialize(@bus : EventBus, @persistence : Persistence::Persistence)+ end++ def run(c : Domain::Credential, rotator : Rotators::Rotator) : Persistence::RotationState+ rotation_id = UUID.random+ record = Persistence::RotationRecord.new(+ id: rotation_id,+ credential_id: c.id,+ rotator_kind: kind_to_enum(rotator.kind),+ state: Persistence::RotationState::Generating,+ started_at: Time.utc,+ completed_at: nil,+ failure_reason: nil,+ )+ @persistence.rotations.insert(record)+ @bus.publish Events::RotationStarted.new(c.id, rotation_id, rotator.kind.to_s)++ new_secret = nil+ current_step = :generate+ begin+ @bus.publish Events::RotationStepStarted.new(c.id, rotation_id, :generate)+ new_secret = rotator.generate(c)+ @persistence.rotations.update_state(rotation_id, Persistence::RotationState::Applying)+ @bus.publish Events::RotationStepCompleted.new(c.id, rotation_id, :generate)++ current_step = :apply+ @bus.publish Events::RotationStepStarted.new(c.id, rotation_id, :apply)+ rotator.apply(c, new_secret)+ @persistence.rotations.update_state(rotation_id, Persistence::RotationState::Verifying)+ @bus.publish Events::RotationStepCompleted.new(c.id, rotation_id, :apply)++ current_step = :verify+ @bus.publish Events::RotationStepStarted.new(c.id, rotation_id, :verify)+ ok = rotator.verify(c, new_secret)+ raise VerifyFailed.new("verify returned false") unless ok+ @persistence.rotations.update_state(rotation_id, Persistence::RotationState::Committing)+ @bus.publish Events::RotationStepCompleted.new(c.id, rotation_id, :verify)++ current_step = :commit+ @bus.publish Events::RotationStepStarted.new(c.id, rotation_id, :commit)+ rotator.commit(c, new_secret)+ @persistence.rotations.update_state(rotation_id, Persistence::RotationState::Completed)+ @bus.publish Events::RotationStepCompleted.new(c.id, rotation_id, :commit)++ @bus.publish Events::RotationCompleted.new(c.id, rotation_id)+ Persistence::RotationState::Completed+ rescue ex+ if ns = new_secret+ if current_step == :apply || current_step == :verify+ begin+ rotator.rollback_apply(c, ns)+ rescue rb+ Log.error(exception: rb) { "rollback_apply failed for credential #{c.id}" }+ end+ end+ end+ @persistence.rotations.update_state(rotation_id, Persistence::RotationState::Failed, ex.message || ex.class.name)+ @bus.publish Events::RotationStepFailed.new(c.id, rotation_id, current_step, ex.message || ex.class.name)+ @bus.publish Events::RotationFailed.new(c.id, rotation_id, ex.message || ex.class.name)+ Persistence::RotationState::Failed+ end+ end++ private def kind_to_enum(kind : Symbol) : Persistence::RotatorKind+ case kind+ when :aws_secretsmgr then Persistence::RotatorKind::AwsSecretsmgr+ when :vault_dynamic then Persistence::RotatorKind::VaultDynamic+ when :github_pat then Persistence::RotatorKind::GithubPat+ when :env_file then Persistence::RotatorKind::EnvFile+ else raise "unknown rotator kind #{kind}"+ end+ end+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/rotators/env_file.cr b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/rotators/env_file.crnew file mode 100644index 00000000..201a6a3d--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/rotators/env_file.cr@@ -0,0 +1,78 @@+# ===================+# ©AngelaMos | 2026+# env_file.cr+# ===================++require "../crypto/random"+require "./rotator"++module CRE::Rotators+ # EnvFileRotator manages credentials stored as KEY=value lines in a .env file.+ # The rotation produces fresh random bytes (base64-encoded) and atomically+ # swaps the live file on commit using temp+rename.+ #+ # Credential.tags must include:+ # "path" - absolute path to the .env file+ # "key" - the key whose value rotates+ class EnvFileRotator < Rotator+ register_as :env_file++ DEFAULT_BYTES = 32++ def kind : Symbol+ :env_file+ end++ def can_rotate?(c : Domain::Credential) : Bool+ c.kind.env_file? && !c.tag("path").nil? && !c.tag("key").nil?+ end++ def generate(c : Domain::Credential) : Domain::NewSecret+ raise RotatorError.new("missing 'path' or 'key' tag") unless can_rotate?(c)+ bytes = (c.tag("bytes") || DEFAULT_BYTES.to_s).to_i+ raw = CRE::Crypto::Random.bytes(bytes)+ encoded = Base64.urlsafe_encode(raw, padding: false)+ Domain::NewSecret.new(+ ciphertext: encoded.to_slice,+ metadata: {"key" => c.tag("key").not_nil!},+ )+ end++ def apply(c : Domain::Credential, s : Domain::NewSecret) : Nil+ path = c.tag("path").not_nil!+ key = c.tag("key").not_nil!+ pending_path = "#{path}.pending"++ existing = File.exists?(path) ? File.read(path) : ""+ lines = existing.lines.reject { |line| line.strip.starts_with?("#{key}=") }+ new_value = String.new(s.ciphertext)+ lines << "#{key}=#{new_value}\n"++ File.write(pending_path, lines.join, perm: 0o600)+ end++ def verify(c : Domain::Credential, s : Domain::NewSecret) : Bool+ path = c.tag("path").not_nil!+ key = c.tag("key").not_nil!+ pending_path = "#{path}.pending"+ return false unless File.exists?(pending_path)++ content = File.read(pending_path)+ expected_line = "#{key}=#{String.new(s.ciphertext)}"+ content.includes?(expected_line) && content.bytesize > 0+ end++ def commit(c : Domain::Credential, _s : Domain::NewSecret) : Nil+ path = c.tag("path").not_nil!+ pending_path = "#{path}.pending"+ raise RotatorError.new("pending file missing at commit time: #{pending_path}") unless File.exists?(pending_path)+ File.rename(pending_path, path)+ end++ def rollback_apply(c : Domain::Credential, _s : Domain::NewSecret) : Nil+ path = c.tag("path").not_nil!+ pending_path = "#{path}.pending"+ File.delete(pending_path) if File.exists?(pending_path)+ end+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/rotators/rotator.cr b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/rotators/rotator.crnew file mode 100644index 00000000..093187f1--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/rotators/rotator.cr@@ -0,0 +1,39 @@+# ===================+# ©AngelaMos | 2026+# rotator.cr+# ===================++require "../domain/credential"+require "../domain/new_secret"++module CRE::Rotators+ class RotatorError < Exception; end++ abstract class Rotator+ REGISTRY = {} of Symbol => Rotator.class++ abstract def kind : Symbol+ abstract def can_rotate?(c : Domain::Credential) : Bool++ abstract def generate(c : Domain::Credential) : Domain::NewSecret+ abstract def apply(c : Domain::Credential, s : Domain::NewSecret) : Nil+ abstract def verify(c : Domain::Credential, s : Domain::NewSecret) : Bool+ abstract def commit(c : Domain::Credential, s : Domain::NewSecret) : Nil++ # Default no-op; rotators override when apply() creates reversible side effects.+ def rollback_apply(c : Domain::Credential, s : Domain::NewSecret) : Nil+ end++ macro register_as(kind)+ ::CRE::Rotators::Rotator::REGISTRY[{{ kind }}] = self+ end++ def self.for(kind : Symbol) : Rotator.class | Nil+ REGISTRY[kind]?+ end++ def self.registered_kinds : Array(Symbol)+ REGISTRY.keys+ end+ end+end