cirron 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c007b251356de7d4d30dc444f70ce6440b1df51aca80292e1d4f1f6be1f282f
-  data.tar.gz: 168cf0a7b01bf1bf59bcbeba407be5580dfe3f6634f676527284e912eb1e3f8b
+  metadata.gz: 28bb8894ef6331fcd6bae4aa768a71ce98fbf29b3870c83ec215c81dea120dd2
+  data.tar.gz: 54c4983a926fc03bfda415ef785b5ce0046c3a410ad92526c0ed9b8c98be4de8
 SHA512:
-  metadata.gz: 10db47d299a3200ccf6f7e4b7d76825fd1d5433b865b5bdc73f3d0ac1a99198b0b1f2ea340545de3519d087aa42adf4d7dc87cb14bf2e580cdf05e8d3151fc48
-  data.tar.gz: 4b4cbf8ffeb1c032cbd329eb7717d5caa878c2919010e227dac5bd06b78e9c81613052e8276bc98569af8bafdc3ca658223e27ee46f825f92812e39684e737cf
+  metadata.gz: 6a46bd52674c2dd8886521d6c90d93defbbcca383aaf5a685330e75e784060ee4dbeaa5c08f5b8e459950e9b1ba7f53c64e28565a174cb0601dae6ce3c6ba7d4
+  data.tar.gz: b058dab6e5657950507ad766dea5b6edfaa74107656a08cfcd38bc1e48a867f83966cbdc462484e982c42f827b941bf27f15cf290f2396be9036b1302911a7b8

data/README.md

@@ -24,7 +24,7 @@ It can also trace syscalls using +strace+, Linux only!
   Hello
   => Counter(time_enabled_ns: 110260, instruction_count: 15406, branch_misses: 525, page_faults: 0)
 
-=== Syscalls
+=== Tracing Syscalls
 
   $ sudo irb
   irb> require 'cirron'
@@ -38,6 +38,36 @@ It can also trace syscalls using +strace+, Linux only!
   irb> File.write("/tmp/trace", Cirron::to_tef(trace))
   => 267
 
+=== Tampering with Syscalls
+
+Available tampering actions are:
+error: Inject a fault with the specified errno.
+retval: Inject a success with the specified return value.
+signal: Deliver the specified signal on syscall entry.
+delay_enter: Delay syscall entry by the specified time.
+delay_exit: Delay syscall exit by the specified time.
+poke_enter: Modify memory at argN on syscall entry.
+poke_exit: Modify memory at argN on syscall exit.
+syscall: Inject a different syscall instead.
+
+The when argument can be used to specify when to perform the tampering.
+
+See the Tampering section of the [strace manual page](https://man7.org/linux/man-pages/man1/strace.1.html) for more detailed explanaition of the arguments.
+
+```
+$ sudo irb
+irb> require 'cirron'
+
+irb> injector = Cirron.injector
+irb> injector.inject("openat", "error", "ENOSPC")
+irb> injector.inject("openat", "delay_enter", "1s", when_condition="2+2")
+irb> injector.run do
+irb>     # Open now fails with "No space left on device" and every
+irb>     # other call to `openat` will be delayed by 1s.
+irb>     File.open("test.txt", "w")
+irb> end
+```
+
 == Additional Information
 
 For more detailed information, please visit the project's GitHub page: https://github.com/s7nfo/Cirron

data/cirron.gemspec

@@ -6,7 +6,7 @@ require 'pathname'
 
 Gem::Specification.new do |spec|
   spec.name = "cirron"
-  spec.version = "0.3.1"
+  spec.version = "0.4.0"
   spec.authors = ["Matt Stuchlik"]
   spec.email = ["matej.stuchlik@gmail.com"]
 
@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
     "lib/cirronlib.cpp",
     "lib/collector.rb",
     "lib/tracer.rb",
+    "lib/injector.rb",
     "README.md",
     "LICENSE",
     "cirron.gemspec"

data/lib/cirron.rb

@@ -1,2 +1,3 @@
 require_relative 'tracer'
 require_relative 'collector'
+require_relative 'injector'

data/lib/injector.rb

@@ -0,0 +1,64 @@
+require 'tempfile'
+require 'open3'
+
+Rule = Struct.new(:syscall, :action, :value, :when)
+
+module Cirron
+  class Injector
+    VALID_ACTIONS = [
+        'error', 'retval', 'signal', 'syscall', 'delay_enter', 'delay_exit',
+        'poke_enter', 'poke_exit', 'when'
+      ].freeze
+
+    def initialize
+      @rules = []
+    end
+
+    def inject(syscall, action, value, when_condition = nil)
+      unless VALID_ACTIONS.include?(action)
+        raise ArgumentError, "Invalid action: #{action}. Valid actions are: #{VALID_ACTIONS.join(', ')}"
+      end
+
+      @rules << Rule.new(syscall, action, value, when_condition)
+    end
+
+    def run(timeout = 10)
+      trace_file = Tempfile.new('cirron_inject')
+      trace_file_path = trace_file.path
+      trace_file.close
+      trace_file.unlink
+      parent_pid = Process.pid
+
+      cmd = ["strace", "--quiet=attach,exit", "-f", "-o", trace_file_path, "-p", parent_pid.to_s]
+
+      @rules.each do |rule|
+        inject_arg = "inject=#{rule.syscall}:#{rule.action}=#{rule.value}"
+        inject_arg += ":when=#{rule.when}" if rule.when
+        cmd.concat(["-e", inject_arg])
+      end
+
+      strace_proc = spawn(*cmd, :out => "/dev/null", :err => "/dev/null")
+
+      begin
+        deadline = Time.now + timeout
+        until File.exist?(trace_file_path)
+          if Time.now > deadline
+            raise Timeout::Error, "Failed to start strace within #{timeout}s."
+          end
+          sleep 0.1
+        end
+
+        sleep 0.1
+
+        yield if block_given?
+      ensure
+        Process.kill('INT', strace_proc) rescue nil
+        Process.wait(strace_proc) rescue nil
+      end
+    end
+  end
+
+  def self.injector
+    Injector.new
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cirron
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Stuchlik
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-09 00:00:00.000000000 Z
+date: 2024-09-10 00:00:00.000000000 Z
 dependencies: []
 description: "= Cirron\n\nCirron measures a piece of Ruby code and reports back several
   performance counters: \nCPU instruction count, branch misses, page faults and time
@@ -18,14 +18,28 @@ description: "= Cirron\n\nCirron measures a piece of Ruby code and reports back
   Usage\n\n=== Performance Counters\n  $ sudo irb\n  irb(main):001> require 'cirron'\n
   \ => true\n  irb(main):002* c = Cirron::collector do\n  irb(main):003*   puts \"Hello\"\n
   \ irb(main):004> end\n  Hello\n  => Counter(time_enabled_ns: 110260, instruction_count:
-  15406, branch_misses: 525, page_faults: 0)\n\n=== Syscalls\n\n  $ sudo irb\n  irb>
-  require 'cirron'\n  => true\n  irb> trace = Cirron::tracer do\n  irb>  # Your code
-  here\n  irb>  puts \"Hello\"\n  irb> end\n  => [#<Syscall:0x00007c6c1a4b3608 @args=\"1,
-  [{iov_base=\\\"Hello\\\", iov_len=5}, {iov_base=\\\"\\\\n\\\", iov_len=1}], 2\",
-  @duration=\"0.000201\", @name=\"writev\", @pid=\"2261962\", @retval=\"6\", @timestamp=\"1720285300.334976\">]\n
-  \ # Save the trace for ingesting to Perfetto\n  irb> File.write(\"/tmp/trace\",
-  Cirron::to_tef(trace))\n  => 267\n\n== Additional Information\n\nFor more detailed
-  information, please visit the project's GitHub page: https://github.com/s7nfo/Cirron"
+  15406, branch_misses: 525, page_faults: 0)\n\n=== Tracing Syscalls\n\n  $ sudo irb\n
+  \ irb> require 'cirron'\n  => true\n  irb> trace = Cirron::tracer do\n  irb>  #
+  Your code here\n  irb>  puts \"Hello\"\n  irb> end\n  => [#<Syscall:0x00007c6c1a4b3608
+  @args=\"1, [{iov_base=\\\"Hello\\\", iov_len=5}, {iov_base=\\\"\\\\n\\\", iov_len=1}],
+  2\", @duration=\"0.000201\", @name=\"writev\", @pid=\"2261962\", @retval=\"6\",
+  @timestamp=\"1720285300.334976\">]\n  # Save the trace for ingesting to Perfetto\n
+  \ irb> File.write(\"/tmp/trace\", Cirron::to_tef(trace))\n  => 267\n\n=== Tampering
+  with Syscalls\n\nAvailable tampering actions are:\nerror: Inject a fault with the
+  specified errno.\nretval: Inject a success with the specified return value.\nsignal:
+  Deliver the specified signal on syscall entry.\ndelay_enter: Delay syscall entry
+  by the specified time.\ndelay_exit: Delay syscall exit by the specified time.\npoke_enter:
+  Modify memory at argN on syscall entry.\npoke_exit: Modify memory at argN on syscall
+  exit.\nsyscall: Inject a different syscall instead.\n\nThe when argument can be
+  used to specify when to perform the tampering.\n\nSee the Tampering section of the
+  [strace manual page](https://man7.org/linux/man-pages/man1/strace.1.html) for more
+  detailed explanaition of the arguments.\n\n```\n$ sudo irb\nirb> require 'cirron'\n\nirb>
+  injector = Cirron.injector\nirb> injector.inject(\"openat\", \"error\", \"ENOSPC\")\nirb>
+  injector.inject(\"openat\", \"delay_enter\", \"1s\", when_condition=\"2+2\")\nirb>
+  injector.run do\nirb>     # Open now fails with \"No space left on device\" and
+  every\nirb>     # other call to `openat` will be delayed by 1s.\nirb>     File.open(\"test.txt\",
+  \"w\")\nirb> end\n```\n\n== Additional Information\n\nFor more detailed information,
+  please visit the project's GitHub page: https://github.com/s7nfo/Cirron"
 email:
 - matej.stuchlik@gmail.com
 executables: []
@@ -39,6 +53,7 @@ files:
 - lib/cirron.rb
 - lib/cirronlib.cpp
 - lib/collector.rb
+- lib/injector.rb
 - lib/tracer.rb
 homepage: https://github.com/s7nfo/Cirron
 licenses: