cassette_guard 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,138 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CassetteGuard
4
+ class Scrubber
5
+ BOUNDARY_CHARS = "A-Za-z0-9"
6
+
7
+ Replacement = Data.define(:finding, :fake) do
8
+ def value = finding.value
9
+
10
+ def header?
11
+ finding.kind.start_with?("header:", "cookie:")
12
+ end
13
+
14
+ def header_name
15
+ finding.location.to_s[/\.headers\.(.+)\z/, 1]
16
+ end
17
+
18
+ def uri_password?
19
+ finding.kind == "uri:password"
20
+ end
21
+
22
+ # Long, distinctive values are replaced wherever they appear (a token issued in one response and
23
+ # sent back in the next request). Short ones such as a first name are only replaced next to their key,
24
+ # so a passenger called Paris leaves the station called Paris alone.
25
+ def global?
26
+ return value.length >= 8 if header? || uri_password?
27
+ return true if finding.key.nil?
28
+
29
+ value.length >= 8 && (finding.rule == :secret || value.match?(/[\d@]/))
30
+ end
31
+ end
32
+
33
+ def initialize(config, only_responses: false)
34
+ @fakes = FakeValue.new(config.salt)
35
+ @sides = only_responses ? %w[response] : %w[request response]
36
+ end
37
+
38
+ # Every pattern a plan needs, built once per cassette rather than once per string.
39
+ # global: [[literal, regex, fake]], keyed: [[regex, fake]], headers: {name => [[value, fake]]},
40
+ # uri_passwords: [[":value@", ":fake@"]].
41
+ Rules = Data.define(:global, :keyed, :headers, :uri_passwords)
42
+
43
+ # Rewrites the cassette in memory and returns the replacements it planned.
44
+ def scrub(cassette, findings)
45
+ plan = plan(findings)
46
+ return plan if plan.empty?
47
+
48
+ rules = compile(plan)
49
+ cassette.interactions.each do |interaction|
50
+ @sides.each do |side|
51
+ part = interaction[side]
52
+ rewrite(part, rules) if part.is_a?(Hash)
53
+ end
54
+ end
55
+ plan
56
+ end
57
+
58
+ private
59
+
60
+ def plan(findings)
61
+ findings.select { |finding| finding.sensitive? && finding.value }
62
+ .uniq { |finding| [finding.value, finding.key, finding.kind] }
63
+ .map { |finding| Replacement.new(finding:, fake: @fakes.for(finding.value, rule: finding.rule)) }
64
+ .sort_by { |replacement| -replacement.value.length }
65
+ end
66
+
67
+ def compile(plan)
68
+ global, local = plan.partition(&:global?)
69
+ Rules.new(
70
+ global: global.flat_map do |replacement|
71
+ Encodings.variants(replacement.value, replacement.fake).map { |original, fake| [original, boundary(original), fake] }
72
+ end,
73
+ keyed: local.select { |replacement| replacement.finding.key }.flat_map do |replacement|
74
+ Encodings.keyed_patterns(replacement.finding.key, replacement.value, replacement.fake)
75
+ end,
76
+ headers: plan.select(&:header?).group_by { |replacement| replacement.header_name.to_s.downcase }
77
+ .transform_values { |replacements| replacements.map { |replacement| [replacement.value, replacement.fake] } },
78
+ uri_passwords: plan.select(&:uri_password?).map do |replacement|
79
+ [":#{Encodings.uri_component(replacement.value)}@", ":#{Encodings.uri_component(replacement.fake)}@"]
80
+ end,
81
+ )
82
+ end
83
+
84
+ def rewrite(part, rules)
85
+ part["uri"] = rewrite_uri(part["uri"], rules) if part["uri"].is_a?(String)
86
+ rewrite_headers(part["headers"], rules) if part["headers"].is_a?(Hash)
87
+ body = Body.for(part)
88
+ rewrite_body(part, body, rules) if body
89
+ end
90
+
91
+ def rewrite_uri(uri, rules)
92
+ uri = apply_keyed(apply_global(uri, rules), rules)
93
+ rules.uri_passwords.reduce(uri) { |text, (original, fake)| text.gsub(original) { fake } }
94
+ end
95
+
96
+ # Values that are not strings (a Plain read from a vcrpy cassette) stay as they are unless they changed.
97
+ def rewrite_headers(headers, rules)
98
+ headers.each_key do |name|
99
+ values = headers[name]
100
+ rewrite = lambda do |value|
101
+ rewritten = rewrite_header(name, value.to_s, rules)
102
+ rewritten == value.to_s ? value : rewritten
103
+ end
104
+ headers[name] = values.is_a?(Array) ? values.map(&rewrite) : rewrite.call(values)
105
+ end
106
+ end
107
+
108
+ def rewrite_header(name, value, rules)
109
+ value = apply_global(value, rules)
110
+ rules.headers.fetch(name.to_s.downcase, []).reduce(value) { |text, (original, fake)| text.gsub(original) { fake } }
111
+ end
112
+
113
+ def rewrite_body(part, body, rules)
114
+ return if body.binary?
115
+
116
+ text = apply_keyed(apply_global(body.text, rules), rules)
117
+ return if text == body.text
118
+
119
+ old_size = body.size
120
+ body.text = text
121
+ Headers.update_content_length(part["headers"], old_size, body.size)
122
+ end
123
+
124
+ def apply_global(text, rules)
125
+ rules.global.reduce(text) do |acc, (original, pattern, fake)|
126
+ acc.include?(original) ? acc.gsub(pattern) { fake } : acc
127
+ end
128
+ end
129
+
130
+ def apply_keyed(text, rules)
131
+ rules.keyed.reduce(text) { |acc, (pattern, fake)| acc.gsub(pattern) { "#{Regexp.last_match(1)}#{fake}" } }
132
+ end
133
+
134
+ def boundary(original)
135
+ /(?<![#{BOUNDARY_CHARS}])#{Regexp.escape(original)}(?![#{BOUNDARY_CHARS}])/
136
+ end
137
+ end
138
+ end
@@ -0,0 +1,70 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CassetteGuard
4
+ # Replaces large binary bodies, and large base64 fields inside text bodies, with a short stub
5
+ # that records what was there.
6
+ class Trimmer
7
+ Trimmed = Data.define(:interaction, :location, :bytes, :content_type)
8
+ BASE64 = %r{\A[A-Za-z0-9+/=_\-\r\n]+\z}
9
+ # Below this, an alphanumeric field is as likely to be a name or a token as an encoded file.
10
+ FIELD_FLOOR = 1024
11
+
12
+ def initialize(min_size:)
13
+ @min_size = min_size
14
+ end
15
+
16
+ def trim(cassette)
17
+ trimmed = []
18
+ cassette.interactions.each_with_index do |interaction, index|
19
+ %w[request response].each do |side|
20
+ body = interaction[side].is_a?(Hash) && Body.for(interaction[side])
21
+ next unless body
22
+
23
+ part = interaction[side]
24
+ trimmed.concat(body.binary? ? trim_body(part, body, side, index) : trim_fields(part, body, side, index))
25
+ end
26
+ end
27
+ trimmed
28
+ end
29
+
30
+ private
31
+
32
+ def trim_body(part, body, side, index)
33
+ size = body.size
34
+ return [] if size < @min_size
35
+
36
+ stub = stub(size, body.content_type || "binary body", body.raw_bytes)
37
+ Headers.delete(part["headers"], "content-encoding") if body.gzipped?
38
+ body.replace(stub)
39
+ Headers.update_content_length(part["headers"], size, stub.bytesize)
40
+ [Trimmed.new(interaction: index, location: "#{side}.body", bytes: size, content_type: body.content_type)]
41
+ end
42
+
43
+ def trim_fields(part, body, side, index)
44
+ min_size = [@min_size, FIELD_FLOOR].max
45
+ return [] if body.text.nil? || body.text.bytesize < min_size
46
+
47
+ fields = Fields.from_text(body.text, body.content_type).select do |field|
48
+ field.key && field.value.bytesize >= min_size && field.value.match?(BASE64)
49
+ end
50
+ return [] if fields.empty?
51
+
52
+ old_size = body.size
53
+ body.text = fields.reduce(body.text) do |text, field|
54
+ replacement = [stub(field.value.bytesize, "base64 field", field.value)].pack("m0")
55
+ Encodings.variants(field.value, replacement).reduce(text) do |current, (original, stub)|
56
+ current.gsub(original) { stub }
57
+ end
58
+ end
59
+ Headers.update_content_length(part["headers"], old_size, body.size)
60
+ fields.map do |field|
61
+ Trimmed.new(interaction: index, location: "#{side}.body #{field.path}", bytes: field.value.bytesize,
62
+ content_type: "base64 field")
63
+ end
64
+ end
65
+
66
+ def stub(size, type, bytes)
67
+ "#{Rules::TRIM_PREFIX} #{Format.bytes(size)} #{type}, sha256:#{Digest::SHA256.hexdigest(bytes)[0, 16]}"
68
+ end
69
+ end
70
+ end
@@ -0,0 +1,47 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "fileutils"
4
+
5
+ module CassetteGuard
6
+ # Load from your test helper, after VCR:
7
+ #
8
+ # require "cassette_guard/usage"
9
+ # CassetteGuard::Usage.track!
10
+ #
11
+ # Every cassette a test inserts is appended to tmp/cassette_guard/usage-<pid>.txt as an absolute path,
12
+ # one file per process so parallel test runners don't collide. `cassette_guard audit` reads them back,
13
+ # whichever directory the tests and the audit run from.
14
+ module Usage
15
+ DEFAULT_DIR = "tmp/cassette_guard"
16
+
17
+ module Hook
18
+ def insert_cassette(name, options = {})
19
+ cassette = super
20
+ CassetteGuard::Usage.record(cassette)
21
+ cassette
22
+ end
23
+ end
24
+
25
+ class << self
26
+ def track!(dir: ENV.fetch("CASSETTE_GUARD_USAGE_DIR", DEFAULT_DIR))
27
+ raise ArgumentError, "require \"vcr\" before calling CassetteGuard::Usage.track!" unless defined?(::VCR)
28
+
29
+ @dir = File.expand_path(dir)
30
+ @seen = {}
31
+ FileUtils.mkdir_p(@dir)
32
+ ::VCR.singleton_class.prepend(Hook) unless ::VCR.singleton_class.ancestors.include?(Hook)
33
+ self
34
+ end
35
+
36
+ def record(cassette)
37
+ return unless @dir && cassette.respond_to?(:file)
38
+
39
+ file = cassette.file
40
+ return if file.nil? || @seen[file]
41
+
42
+ @seen[file] = true
43
+ File.open(File.join(@dir, "usage-#{Process.pid}.txt"), "a") { |out| out.puts(File.expand_path(file)) }
44
+ end
45
+ end
46
+ end
47
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CassetteGuard
4
+ VERSION = "0.1.0"
5
+ end
@@ -0,0 +1,40 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "date"
4
+ require "digest"
5
+ require "json"
6
+ require "time"
7
+ require "uri"
8
+ require "yaml"
9
+
10
+ module CassetteGuard
11
+ class Error < StandardError; end
12
+ end
13
+
14
+ require_relative "cassette_guard/version"
15
+ require_relative "cassette_guard/format"
16
+ require_relative "cassette_guard/rules"
17
+ require_relative "cassette_guard/config"
18
+ require_relative "cassette_guard/finding"
19
+ require_relative "cassette_guard/finding_group"
20
+ require_relative "cassette_guard/encodings"
21
+ require_relative "cassette_guard/headers"
22
+ require_relative "cassette_guard/body"
23
+ require_relative "cassette_guard/fields"
24
+ require_relative "cassette_guard/py_yaml"
25
+ require_relative "cassette_guard/cassette"
26
+ require_relative "cassette_guard/detectors/secret"
27
+ require_relative "cassette_guard/detectors/pii"
28
+ require_relative "cassette_guard/detectors/size"
29
+ require_relative "cassette_guard/detectors/age"
30
+ require_relative "cassette_guard/detectors/usage"
31
+ require_relative "cassette_guard/scanner"
32
+ require_relative "cassette_guard/fake_value"
33
+ require_relative "cassette_guard/scrubber"
34
+ require_relative "cassette_guard/trimmer"
35
+ require_relative "cassette_guard/baseline"
36
+ require_relative "cassette_guard/line_locator"
37
+ require_relative "cassette_guard/reporters/text"
38
+ require_relative "cassette_guard/reporters/json"
39
+ require_relative "cassette_guard/reporters/sarif"
40
+ require_relative "cassette_guard/cli"
metadata ADDED
@@ -0,0 +1,84 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: cassette_guard
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - Opara Ifeanyi Christian
8
+ autorequire:
9
+ bindir: exe
10
+ cert_chain: []
11
+ date: 2026-11-19 00:00:00.000000000 Z
12
+ dependencies: []
13
+ description: |
14
+ cassette_guard audits Ruby VCR and Python vcrpy cassettes for credentials, personal data, oversized bodies, old recordings and
15
+ cassettes no test loads any more. It scrubs what it finds with deterministic, format-preserving fakes,
16
+ trims large binary bodies, and runs in CI with a baseline so only new findings fail the build.
17
+ email:
18
+ executables:
19
+ - cassette_guard
20
+ extensions: []
21
+ extra_rdoc_files: []
22
+ files:
23
+ - CHANGELOG.md
24
+ - LICENSE.txt
25
+ - README.md
26
+ - exe/cassette_guard
27
+ - lib/cassette_guard.rb
28
+ - lib/cassette_guard/baseline.rb
29
+ - lib/cassette_guard/body.rb
30
+ - lib/cassette_guard/cassette.rb
31
+ - lib/cassette_guard/cli.rb
32
+ - lib/cassette_guard/config.rb
33
+ - lib/cassette_guard/detectors/age.rb
34
+ - lib/cassette_guard/detectors/pii.rb
35
+ - lib/cassette_guard/detectors/secret.rb
36
+ - lib/cassette_guard/detectors/size.rb
37
+ - lib/cassette_guard/detectors/usage.rb
38
+ - lib/cassette_guard/encodings.rb
39
+ - lib/cassette_guard/fake_value.rb
40
+ - lib/cassette_guard/fields.rb
41
+ - lib/cassette_guard/finding.rb
42
+ - lib/cassette_guard/finding_group.rb
43
+ - lib/cassette_guard/format.rb
44
+ - lib/cassette_guard/headers.rb
45
+ - lib/cassette_guard/line_locator.rb
46
+ - lib/cassette_guard/py_yaml.rb
47
+ - lib/cassette_guard/reporters/json.rb
48
+ - lib/cassette_guard/reporters/sarif.rb
49
+ - lib/cassette_guard/reporters/text.rb
50
+ - lib/cassette_guard/rules.rb
51
+ - lib/cassette_guard/scanner.rb
52
+ - lib/cassette_guard/scrubber.rb
53
+ - lib/cassette_guard/trimmer.rb
54
+ - lib/cassette_guard/usage.rb
55
+ - lib/cassette_guard/version.rb
56
+ homepage: https://gitlab.com/chrisgeeq/cassette_guard
57
+ licenses:
58
+ - MIT
59
+ metadata:
60
+ source_code_uri: https://gitlab.com/chrisgeeq/cassette_guard
61
+ changelog_uri: https://gitlab.com/chrisgeeq/cassette_guard/-/blob/main/CHANGELOG.md
62
+ bug_tracker_uri: https://gitlab.com/chrisgeeq/cassette_guard/-/issues
63
+ rubygems_mfa_required: 'true'
64
+ post_install_message:
65
+ rdoc_options: []
66
+ require_paths:
67
+ - lib
68
+ required_ruby_version: !ruby/object:Gem::Requirement
69
+ requirements:
70
+ - - ">="
71
+ - !ruby/object:Gem::Version
72
+ version: '3.3'
73
+ required_rubygems_version: !ruby/object:Gem::Requirement
74
+ requirements:
75
+ - - ">="
76
+ - !ruby/object:Gem::Version
77
+ version: '0'
78
+ requirements: []
79
+ rubygems_version: 3.5.16
80
+ signing_key:
81
+ specification_version: 4
82
+ summary: Find and scrub secrets, personal data, oversized and unused recordings in
83
+ VCR and vcrpy cassettes.
84
+ test_files: []