ronin-code-asm 1.0.0.beta1

data/lib/ronin/code/asm.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+#
+# ronin-code-asm - A Ruby DSL for crafting Assembly programs and shellcode.
+#
+# Copyright (c) 2007-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-code-asm is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-code-asm is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-code-asm.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/code/asm/program'
+require 'ronin/code/asm/shellcode'
+require 'ronin/code/asm/version'
+
+module Ronin
+  module Code
+    module ASM
+      #
+      # Creates a new Assembly Program.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments for {Program#initialize}.
+      #
+      # @option kwargs [String, Symbol] :arch (:x86)
+      #   The architecture of the Program.
+      #
+      # @option kwargs [Hash{Symbol => Object}] :variables
+      #   Variables to set in the program.
+      #
+      # @yield []
+      #   The given block will be evaluated within the program.
+      #
+      # @return [Program]
+      #   The new Assembly Program.
+      #
+      # @example
+      #   ASM.new do
+      #     mov  1, eax
+      #     mov  1, ebx
+      #     mov  2, ecx
+      #
+      #     _loop do
+      #       push  ecx
+      #       imul  ebx, ecx
+      #       pop   ebx
+      #
+      #       inc eax
+      #       cmp ebx, 10
+      #       jl  :_loop
+      #     end
+      #   end
+      #
+      def ASM.new(**kwargs,&block)
+        Program.new(**kwargs,&block)
+      end
+    end
+  end
+end

data/ronin-code-asm.gemspec

@@ -0,0 +1,62 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'ronin/code/asm/version'
+                  Ronin::Code::ASM::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files  = `git ls-files`.split($/)
+  gem.files  = glob[gemspec['files']] if gemspec['files']
+  gem.files += Array(gemspec['generated_files'])
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || 'spec/{**/}*_spec.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/spec/asm_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+require 'ronin/code/asm'
+
+describe Ronin::Code::ASM do
+  it "must have a version" do
+    expect(subject.const_defined?('VERSION')).to eq(true)
+  end
+
+  describe ".new" do
+    it "must return a new Ronin::Code::ASM::Program" do
+      expect(subject.new(arch: :x86)).to be_kind_of(Ronin::Code::ASM::Program)
+    end
+  end
+end

data/spec/config_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+require 'ronin/code/asm/config'
+
+describe Ronin::Code::ASM::Config do
+  describe "DATA_DIR" do
+    it "must be a directory" do
+      expect(File.directory?(subject::DATA_DIR)).to be(true)
+    end
+  end
+end

data/spec/immediate_operand_spec.rb

@@ -0,0 +1,79 @@
+require 'spec_helper'
+
+require 'ronin/code/asm/immediate_operand'
+
+describe Ronin::Code::ASM::ImmediateOperand do
+  let(:value) { 0xff }
+
+  describe "#initialize" do
+    context "with a width" do
+      let(:width) { 2 }
+
+      subject { described_class.new(value,width) }
+
+      it "must set the width" do
+        expect(subject.width).to eq(width)
+      end
+    end
+  end
+
+  describe "#width" do
+    describe "default width for" do
+      context "0x100000000 .. 0xffffffffffffffff" do
+        subject { described_class.new(0xffffffffffffffff).width }
+
+        it { expect(subject).to be == 8 }
+      end
+
+      context "-0x800000000 .. -0x7fffffffffffffff" do
+        subject { described_class.new(-0x7fffffffffffffff).width }
+
+        it { expect(subject).to be == 8 }
+      end
+
+      context "0x10000 .. 0xffffffff" do
+        subject { described_class.new(0xffffffff).width }
+
+        it { expect(subject).to be == 4 }
+      end
+
+      context "-0x80000 .. -0x7fffffff" do
+        subject { described_class.new(-0x7fffffff).width }
+
+        it { expect(subject).to be == 4 }
+      end
+
+      context "0x100 .. 0xffff" do
+        subject { described_class.new(0xffff).width }
+
+        it { expect(subject).to be == 2 }
+      end
+
+      context "-0x80 .. -0x7fff" do
+        subject { described_class.new(-0x7fff).width }
+
+        it { expect(subject).to be == 2 }
+      end
+
+      context "0x0 .. 0xff" do
+        subject { described_class.new(0xff).width }
+
+        it { expect(subject).to be == 1 }
+      end
+
+      context "0x0 .. -0x7f" do
+        subject { described_class.new(-0x7f).width }
+
+        it { expect(subject).to be == 1 }
+      end
+    end
+  end
+
+  describe "#to_i" do
+    subject { described_class.new(value) }
+
+    it "must return the value" do
+      expect(subject.to_i).to eq(value)
+    end
+  end
+end

data/spec/instruction_spec.rb

@@ -0,0 +1,62 @@
+require 'spec_helper'
+
+require 'ronin/code/asm/instruction'
+require 'ronin/code/asm/register'
+require 'ronin/code/asm/immediate_operand'
+require 'ronin/code/asm/memory_operand'
+
+describe Ronin::Code::ASM::Instruction do
+  let(:register)  { Ronin::Code::ASM::Register.new(:eax, 4) }
+  let(:immediate) { Ronin::Code::ASM::ImmediateOperand.new(0xff, 1) }
+
+  describe "#initialize" do
+    let(:name)     { :mov }
+    let(:operands) { [immediate, register] }
+
+    subject { described_class.new(name,operands) }
+
+    it "must set the name" do
+      expect(subject.name).to eq(:mov)
+    end
+
+    it "must set the operands" do
+      expect(subject.operands).to eq(operands)
+    end
+
+    context "when given an Integer operand" do
+      let(:integer) { 0xff }
+
+      subject { described_class.new(name, [integer, register]) }
+
+      it "must wrap the operand to in a Ronin::Code::ASM::ImmediateOperand" do
+        expect(subject.operands[0]).to be_kind_of(Ronin::Code::ASM::ImmediateOperand)
+        expect(subject.operands[0].value).to eq(integer)
+      end
+    end
+
+    context "when given a nil operand" do
+      subject { described_class.new(name, [nil, register]) }
+
+      it "must wrap the operand to in a Ronin::Code::ASM::ImmediateOperand" do
+        expect(subject.operands[0]).to be_kind_of(Ronin::Code::ASM::ImmediateOperand)
+        expect(subject.operands[0].value).to eq(0)
+      end
+    end
+  end
+
+  describe "#width" do
+    subject { described_class.new(:mov, [immediate, register]) }
+
+    it "must return the maximum width of the operands" do
+      expect(subject.width).to eq(register.width)
+    end
+
+    context "when one of the operands does not define #width" do
+      subject { described_class.new(:mov, [:label, register]) }
+
+      it "must ignore them" do
+        expect(subject.width).to eq(register.width)
+      end
+    end
+  end
+end

data/spec/memory_operand_spec.rb

@@ -0,0 +1,80 @@
+require 'spec_helper'
+
+require 'ronin/code/asm/memory_operand'
+require 'ronin/code/asm/register'
+
+describe Ronin::Code::ASM::MemoryOperand do
+  let(:register) { Ronin::Code::ASM::Register.new(:eax, 4) }
+
+  describe "#initialize" do
+    it { expect(subject.base).to   be_nil }
+    it { expect(subject.offset).to eq(0)  }
+    it { expect(subject.index).to  be_nil }
+    it { expect(subject.scale).to  eq(1)  }
+
+    it "must only accept nil and a Register for base" do
+      expect {
+        described_class.new(Object.new)
+      }.to raise_error(TypeError)
+    end
+
+    it "must only accept Integers for offset" do
+      expect {
+        described_class.new(register,2.0)
+      }.to raise_error(TypeError)
+    end
+
+    it "must only accept nil and a Register for index" do
+      expect {
+        described_class.new(register,0,Object.new)
+      }.to raise_error(TypeError)
+    end
+
+    it "must only accept Integers for offset" do
+      expect {
+        described_class.new(register,0,nil,2.0)
+      }.to raise_error(TypeError)
+    end
+
+  end
+
+  describe "#+" do
+    let(:operand) { described_class.new(register,4,register,2) }
+
+    subject { operand + 4 }
+
+    it "must add to offset" do
+      expect(subject.offset).to eq(8)
+    end
+
+    it "must not change base, index or scale" do
+      expect(subject.base).to  eq(operand.base)
+      expect(subject.index).to eq(operand.index)
+      expect(subject.scale).to eq(operand.scale)
+    end
+  end
+
+  describe "#-" do
+    let(:operand) { described_class.new(register,4,register,2) }
+
+    subject { operand - 2 }
+
+    it "must subtract from offset" do
+      expect(subject.offset).to eq(2)
+    end
+
+    it "must not change base, index or scale" do
+      expect(subject.base).to  eq(operand.base)
+      expect(subject.index).to eq(operand.index)
+      expect(subject.scale).to eq(operand.scale)
+    end
+  end
+
+  describe "#width" do
+    subject { described_class.new(register,10) }
+
+    it "must return the width of base" do
+      expect(subject.width).to eq(register.width)
+    end
+  end
+end

data/spec/os_spec.rb

@@ -0,0 +1,68 @@
+require 'spec_helper'
+require 'ronin/code/asm/os'
+
+describe Ronin::Code::ASM::OS do
+  describe "SYSCALLS" do
+    subject { described_class::SYSCALLS }
+
+    let(:data_dir) { Ronin::Code::ASM::Config::DATA_DIR }
+
+    it { expect(subject).to be_kind_of(Hash) }
+
+    it "must load syscalls for :freebsd and :amd64" do
+      expect(subject[:freebsd][:amd64]).to eq(
+        YAML.load_file(
+          File.join(data_dir,'os','freebsd','amd64','syscalls.yml')
+        )
+      )
+    end
+
+    it "must load syscalls for :freebsd and :x86" do
+      expect(subject[:freebsd][:amd64]).to eq(
+        YAML.load_file(
+          File.join(data_dir,'os','freebsd','x86','syscalls.yml')
+        )
+      )
+    end
+
+    it "must load syscalls for :linux and :amd64" do
+      expect(subject[:linux][:amd64]).to eq(
+        YAML.load_file(
+          File.join(data_dir,'os','linux','amd64','syscalls.yml')
+        )
+      )
+    end
+
+    it "must load syscalls for :linux and :x86" do
+      expect(subject[:linux][:x86]).to eq(
+        YAML.load_file(
+          File.join(data_dir,'os','linux','x86','syscalls.yml')
+        )
+      )
+    end
+  end
+
+  describe ".[]" do
+    context "when given :linux" do
+      it "must return #{described_class}::Linux" do
+        expect(subject[:linux]).to be(described_class::Linux)
+      end
+    end
+
+    context "when given :freebsd" do
+      it "must return #{described_class}::FreeBSD" do
+        expect(subject[:freebsd]).to be(described_class::FreeBSD)
+      end
+    end
+
+    context "when given an unknown Symbol" do
+      let(:name) { :foo }
+
+      it do
+        expect {
+          subject[name]
+        }.to raise_error(ArgumentError,"unknown OS name: #{name.inspect}")
+      end
+    end
+  end
+end