corruption_monkey 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4b6874de9bd4a6d99c99d10e6ffa8ff196d0e380
+  data.tar.gz: 74071c21f62bbecb7a1010a0c1facd60eda9ddf9
+SHA512:
+  metadata.gz: 9beb55581474d4f6e9ea3976da3c2566c33f24e63d9d21617613a5905188addd44f7cb9648fe021a6ba1de86c04bca409bb5f4e1f58c05b4af6c690c2ff2ee49
+  data.tar.gz: a8eaa52a59155d0a93aee547888ac985621f144e6233c7ceb14862a53c64fb62f03bc8ef5969428cc05e03d2a8cdea6af7db887ead36183a7fdfe63a0fc41475

data/.gitignore

@@ -0,0 +1,32 @@
+# Vim
+[._]*.s[a-w][a-z]
+[._]s[a-w][a-z]
+# session
+Session.vim
+.netrwhist
+*~
+tags
+
+# Ruby
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/

data/.ruby-version

@@ -0,0 +1 @@
+2.3.1

data/CONTRIBUTING.md

@@ -0,0 +1,5 @@
+#### How to contribute to corruption_monkey
+
+Open an issue/ pull request :)
+
+Thanks! :revolving_hearts: 

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+group :development, :test do
+  gem 'rake'
+  gem 'minitest'
+end
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,21 @@
+PATH
+  remote: .
+  specs:
+    corruption_monkey (0.1.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.9.0)
+    rake (11.2.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  corruption_monkey!
+  minitest
+  rake
+
+BUNDLED WITH
+   1.12.5

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Shopify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,61 @@
+### Corruption monkey
+TL;DR: do 🔬  with backups (and 🐒)
+
+This Ruby library (and CLI) provides an easy way to flip bits in a provided file.
+
+It was built in order to corrupt database backups and test if our current and future tools work and calculate their coverage.
+
+#### Local installation
+```bash
+$ gem install corruption_monkey
+```
+or
+```bash
+$ git clone https://github.com/Shopify/corruption_monkey && cd corruption_monkey
+$ rake install
+```
+
+#### CLI
+```bash
+# flip a bit in a specific bit index
+$ flip <file> <position>
+
+# flip a bit in some part of the file
+$ flip <file> <percent>%
+
+# flip a bit... somewhere ¯\_(ツ)_/¯
+$ flip <file> chaos
+
+# show help message with this examples
+$ flip [help]
+
+```
+#### API
+```ruby
+require 'tempfile'
+require 'logger'
+require 'corruption_monkey'
+
+file = Tempfile.new('whatever')
+file_path = file.path
+logger = Logger.new(nil)
+
+# flip a bit in a specific bit index
+BitFlipper.random_bit_flip(file_path, bit: 40, logger: logger)
+
+# flip a bit in some part of thefile
+BitFlipper.flip_in_range(file_path, percentile: 4, logger: logger)
+
+# flip a bit... somewhere ¯\_(ツ)_/¯
+BitFlipper.random_bit_flip(file_path, logger: logger)
+
+```
+
+#### Extra
+You can generate png glitch art, too.
+![image](https://cloud.githubusercontent.com/assets/959128/17756485/235c13ae-64ae-11e6-8583-5e606bcb45f3.png)
+
+(From https://en.wikipedia.org/wiki/Portable_Network_Graphics)
+
+#### ⚠️Caution!
+This lib may improve your bit flipping skills.

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+
+task default: :test
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/*test.rb']
+end

data/bin/flip

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'corruption_monkey/cli'
+
+BitFlipper::CLI.start

data/corruption_monkey.gemspec

@@ -0,0 +1,18 @@
+$LOAD_PATH << 'lib'
+require 'corruption_monkey/version'
+
+Gem::Specification.new do |gem|
+  gem.authors       = %w(Javier Honduvilla Coto)
+  gem.email         = %w(javier.honduvilla@shopify.com javierhonduco@gmail.com)
+  gem.description   = 'Bit flipping tool.'
+  gem.summary       = 'Library and CLI to flip a bit in a provided file.'
+  gem.homepage      = 'https://github.com/Shopify/corruption_monkey'
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^test/})
+  gem.name          = 'corruption_monkey'
+  gem.require_paths = ['lib']
+
+  gem.version       = BitFlipper::VERSION
+end

data/lib/corruption_monkey/cli.rb

@@ -0,0 +1,67 @@
+require 'corruption_monkey'
+
+module BitFlipper::CLI
+  DOCS = <<-DOCS
+  CLI options:
+
+    1. Specific bit flip (by absolute or relative indexing)
+      $ flip <file_path> (<bit_index>|<percentage of file>%)
+
+    2. Chaos mode (randomized)
+      $ flip <file_path> chaos
+
+  To display help:
+    $ flip help
+  DOCS
+
+  def self.banner(s = $stdout)
+    s.puts '🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 '
+    s.puts '🔥 bit flipper chaos 🙈  CLI🔥'
+    s.puts '🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 '
+    s.puts
+  end
+
+  def self.start(args = ARGV)
+    file_path = args.shift
+    second_argument = args.shift
+
+    # Empty imput or docs request
+    if (file_path.nil? && second_argument.nil?) ||
+        (!File.file?(file_path) && file_path == 'help')
+      puts DOCS
+      exit 0
+    end
+
+    # First argument is not a (existing) file
+    unless File.file?(file_path)
+      $stderr.puts "The file with path=`#{file_path}` does not exist"
+      exit 1
+    end
+
+    logger = Logger.new(STDOUT)
+    banner
+
+    case second_argument
+    when 'chaos'
+      puts 'chaos mode selected'
+      puts
+      BitFlipper.random_bit_flip(file_path, logger: logger)
+    when /([0-9]{1, 2}|100)%/
+      # this regex feels... weird
+      puts 'percent mode selected'
+      puts
+      BitFlipper.flip_in_range(file_path,
+                               percentile: second_argument.to_i,
+                               logger: logger)
+    when /[0-9]+/
+      puts 'accurate mode selected'
+      puts
+      BitFlipper.flip!(file_path,
+                       bit: second_argument.to_i,
+                       logger: logger)
+    else
+      $stderr.puts 'nothing matches!'
+      $stderr.puts DOCS
+    end
+  end
+end

data/lib/corruption_monkey/version.rb

@@ -0,0 +1,3 @@
+module BitFlipper
+  VERSION = '0.1.2'
+end

data/lib/corruption_monkey.rb

@@ -0,0 +1,58 @@
+require 'logger'
+
+module BitFlipper
+
+  BitOutOfBounds = Class.new(Exception)
+
+  def self.flip!(target, bit:, logger: Logger.new(nil))
+    logger.debug "going to flip bit with index=#{bit}"
+
+    flip_byte, flip_bit = bit.divmod(8)
+
+    logger.debug "computed [byte, bit]=#{[flip_byte, flip_bit]}"
+
+    file = File.open(target, 'r+')
+
+    file.seek(flip_byte, 0)
+    byte = file.read(1)
+
+    if byte.nil? || out_of_range(target, bit)
+      raise BitOutOfBounds, "#{bit} is bigger than the offset=#{size_in_bits(target)}"
+    end
+
+    new_byte = [byte.unpack('c').first ^ (1 << flip_bit)].pack('c')
+
+    logger.debug "readed byte: `#{byte}`: #{byte.unpack('b*').first}"
+    logger.debug "writing byte: `#{new_byte}` #{new_byte.unpack('b*').first}"
+
+    file.seek(-1, IO::SEEK_CUR)
+    file.write(new_byte)
+
+    file.fsync
+    file.close
+  end
+
+  def self.random_bit_flip(target, logger: Logger.new(nil))
+    computed_bit = rand(0...size_in_bits(target))
+    flip!(target, bit: computed_bit, logger: logger)
+  end
+
+  def self.flip_in_range(target, percentile:, logger: Logger.new(nil))
+    # TODO(javierhonduco): Improve error checking (╯ರ ~ ರ)
+    bit_to_flip = (size_in_bits(target) * percentile/101.0).to_i
+
+    if out_of_range(target, bit_to_flip)
+      raise IndexError, "percentile=#{percentile} not in range"
+    end
+
+    flip!(target, bit: bit_to_flip, logger: logger)
+  end
+
+  def self.size_in_bits(file)
+    File.size(file) * 8
+  end
+
+  def self.out_of_range(file, bit)
+    bit < 0 || bit > size_in_bits(file)
+  end
+end

data/test/cli_test.rb

@@ -0,0 +1,56 @@
+require 'minitest/autorun'
+require 'fileutils'
+require 'corruption_monkey'
+require_relative 'test_helpers'
+
+class TestCLI < Minitest::Test
+  include TestHelpers
+
+  TEST_DIR = "/tmp/bit_flipper_monkey_test_cli_#{rand(0..999)}"
+
+  def setup
+    FileUtils.rm_rf(TEST_DIR) # Ensure clean state
+    FileUtils.mkdir(TEST_DIR)
+  end
+
+  def teardown
+    FileUtils.rm_rf(TEST_DIR)
+  end
+
+  def test_accurate_bit_flip
+    test_file = "#{TEST_DIR}/zeroes"
+    zeroes(test_file)
+
+    run_cli(test_file, '9')
+    assert_equal "\u0000\u0002#{"\u0000" * 8}", File.read(test_file)
+  end
+
+  def test_accurate_percentage_flip
+    test_file = "#{TEST_DIR}/zeroes"
+    zeroes(test_file)
+
+    run_cli(test_file, '0%')
+    assert_equal "\u0001#{"\u0000" * 9}", File.read(test_file)
+  end
+
+  def test_random_bit_flip
+    test_file = "#{TEST_DIR}/zeroes"
+    zeroes(test_file)
+
+    run_cli(test_file, 'chaos')
+    assert_equal 1, hamming_weight(test_file)
+  end
+
+  def test_help
+    run_cli =~ /CLI options:/
+    run_cli('help') =~ /CLI options:/
+  end
+
+  private
+
+  def run_cli(*args)
+    output = `bin/flip #{args * ' '}`
+    raise ProcessExecutionError unless $?.success?
+    output
+  end
+end

data/test/lib_test.rb

@@ -0,0 +1,103 @@
+require 'minitest/autorun'
+require 'fileutils'
+require 'corruption_monkey'
+require_relative 'test_helpers'
+
+class TestBitFlipper < Minitest::Test
+  include TestHelpers
+
+  TEST_DIR = "/tmp/bit_flipper_monkey_test_#{rand(0..999)}"
+
+  def setup
+    FileUtils.rm_rf(TEST_DIR) # Ensure clean state
+    FileUtils.mkdir(TEST_DIR)
+  end
+
+  def teardown
+    FileUtils.rm_rf(TEST_DIR)
+  end
+
+  def test_number_of_changed_bits
+    test_file = "#{TEST_DIR}/zeroes"
+    zeroes(test_file)
+
+    BitFlipper.flip!(test_file, bit: 0)
+    assert_equal 1, hamming_weight(test_file)
+
+    BitFlipper.flip!(test_file, bit: 1)
+    assert_equal 2, hamming_weight(test_file)
+  end
+
+  def test_basic_ascii_mathz
+    test_file = "#{TEST_DIR}/simple_ascii"
+
+    File.open(test_file, 'w') do |f|
+      f.write 'a'
+    end
+
+    BitFlipper.flip!(test_file, bit: 0)
+    BitFlipper.flip!(test_file, bit: 1)
+    assert_equal 'b', File.read(test_file)
+  end
+
+  def test_basic_zeroes
+    test_file = "#{TEST_DIR}/zeroes"
+    zeroes(test_file)
+
+    BitFlipper.flip!(test_file, bit: 9)
+    assert_equal "\u0000\u0002#{"\u0000" * 8}", File.read(test_file)
+  end
+
+  def test_twice_flipped_bit
+    test_file = "#{TEST_DIR}/zeroes"
+    base_file = "#{TEST_DIR}/zeroes_DO_NOT_MODIFY"
+
+    [test_file, base_file].each do |file|
+      zeroes(file)
+    end
+
+    BitFlipper.flip!(test_file, bit: 5)
+    BitFlipper.flip!(test_file, bit: 5)
+    assert_equal File.read(base_file), File.read(test_file)
+
+    BitFlipper.flip!(test_file, bit: 2)
+    BitFlipper.flip!(test_file, bit: 2)
+    assert_equal File.read(base_file), File.read(test_file)
+  end
+
+  def test_percentage
+    test_file = "#{TEST_DIR}/zeroes"
+    zeroes(test_file)
+
+    BitFlipper.flip_in_range(test_file, percentile: 0)
+    assert_equal "\u0001#{"\u0000" * 9}", File.read(test_file)
+    zeroes(test_file)
+
+    BitFlipper.flip_in_range(test_file, percentile: 50)
+    assert_equal "#{"\u0000" * 4}\x80#{"\u0000" * 5}", File.read(test_file)
+    zeroes(test_file)
+
+    BitFlipper.flip_in_range(test_file, percentile: 100)
+    assert_equal "#{"\u0000" * 9}\x80", File.read(test_file)
+  end
+
+  def test_bit_out_of_bounds_error
+    test_file = "#{TEST_DIR}/ascii_out_of_bounds"
+
+    File.open(test_file, 'w') do |f|
+      f.write 'a'
+    end
+
+    assert_raises BitFlipper::BitOutOfBounds do
+      BitFlipper.flip!(test_file, bit: 10)
+    end
+  end
+
+  def test_random_bit_flip
+    test_file = "#{TEST_DIR}/zeroes"
+    zeroes(test_file)
+
+    BitFlipper.random_bit_flip(test_file)
+    assert_equal 1, hamming_weight(test_file)
+  end
+end

data/test/test_helpers.rb

@@ -0,0 +1,17 @@
+module TestHelpers
+  ProcessExecutionError = Class.new(Exception)
+
+  def zeroes(file)
+    `dd if=/dev/zero of=#{file} bs=1 count=10 2> /dev/null`
+    raise ProcessExecutionError unless $?.success?
+  end
+
+  def hamming_weight(file)
+    File.read(file).
+      unpack('b*').
+      first.
+      split(//).
+      map { |b| b == '1' }.
+      count(true)
+  end
+end

data/travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1
+  - 2.3.1

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: corruption_monkey
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Javier
+- Honduvilla
+- Coto
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-09-17 00:00:00.000000000 Z
+dependencies: []
+description: Bit flipping tool.
+email:
+- javier.honduvilla@shopify.com
+- javierhonduco@gmail.com
+executables:
+- flip
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".ruby-version"
+- CONTRIBUTING.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.md
+- README.md
+- Rakefile
+- bin/flip
+- corruption_monkey.gemspec
+- lib/corruption_monkey.rb
+- lib/corruption_monkey/cli.rb
+- lib/corruption_monkey/version.rb
+- test/cli_test.rb
+- test/lib_test.rb
+- test/test_helpers.rb
+- travis.yml
+homepage: https://github.com/Shopify/corruption_monkey
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Library and CLI to flip a bit in a provided file.
+test_files:
+- test/cli_test.rb
+- test/lib_test.rb
+- test/test_helpers.rb