yara 1.4.1 → 1.4.2

data/README.rdoc

@@ -1,4 +1,7 @@
 = yara
+Eric Monti - emonti at trustwave dot com
+
+== Introduction
 
 Ruby bindings for the yara malware analysis library.
 
@@ -8,9 +11,11 @@ based on textual or binary information contained on samples of those families.
 These descriptions, named rules, consist of a set of strings and a Boolean
 expression which determines the rule logic.
 
-See http://code.google.com/p/yara-project for more information.
+Yara and it's code are copyrights of Victor M. Alvarez. Please see
+http://code.google.com/p/yara-project/
+
 
-== Synopsis
+== Usage
 
   # basic example... find all PE files under the current dir
 
@@ -29,15 +34,48 @@ See http://code.google.com/p/yara-project for more information.
   end
 
 == Versioning
-The current version is of libyara at the time of writing 1.4.0. 
+The current version of libyara at the time of writing is 1.4.0. Bindings
+have been written against this API and may not work with earlier versions
+of the libyara library.
+
 The major and minor version numbers of the ruby library are intended
 to be in step with the C api version.
 
 == Requirements
 * libyara 1.4 must be installed - http://code.google.com/p/yara-project/
 
+== Installation
+
+First make sure you have libyara and its dependencies installed. You'll need
+libyara and yara.h in your search paths.
+
+Install the yara ruby package from a gem:
+
+    (sudo)? gem install yara
+
+Or from the github package.
+
+    git clone https://github.com/SpiderLabs/yara-ruby.git
+    cd yara-ruby
+    rake compile
+
+
 == Copyright
+yara-ruby - Ruby bindings for the yara malware analysis library.
+Eric Monti
+Copyright (C) 2011 Trustwave Holdings
+
+This program is free software: you can redistribute it and/or modify it 
+under the terms of the GNU General Public License as published by the 
+Free Software Foundation, either version 3 of the License, or (at your
+option) any later version.
+
+This program 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 General Public License
+for more details.
 
-Copyright (c) 2011 Eric Monti. See LICENSE.txt for
-further details.
+You should have received a copy of the GNU General Public License along
+with this program. If not, see <http://www.gnu.org/licenses/>.
 
+See LICENSE.txt

data/Rakefile

@@ -16,8 +16,8 @@ Jeweler::Tasks.new do |gem|
   # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
   gem.name = "yara"
   gem.homepage = "http://github.com/SpiderLabs/yara-ruby"
-  gem.summary = %Q{Ruby Bindings for libyara}
-  gem.description = %Q{Ruby Bindings for the yara malware analysis library}
+  gem.summary = %Q{Ruby bindings for libyara}
+  gem.description = %Q{Ruby bindings for the yara malware analysis library}
   gem.email = "emonti@trustwave.com"
   gem.authors = ["Eric Monti"]
 
@@ -50,3 +50,13 @@ task :default => :spec
 
 require 'yard'
 YARD::Rake::YardocTask.new
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rd|
+  rd.rdoc_dir = 'rdoc'
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include [ 
+    "README.rdoc", "History.txt", "LICENSE.txt", "VERSION", 
+    "lib/**/*", "ext/**/*.c" ]
+end
+

data/VERSION

@@ -1 +1 @@
-1.4.1
+1.4.2

data/ext/yara_native/Match.c

@@ -1,8 +1,29 @@
-#include "Match.h"
+/*
+ *  yara-ruby - Ruby bindings for the yara malware analysis library.
+ *  Eric Monti
+ *  Copyright (C) 2011 Trustwave Holdings
+ *  
+ *  This program is free software: you can redistribute it and/or modify it 
+ *  under the terms of the GNU General Public License as published by the 
+ *  Free Software Foundation, either version 3 of the License, or (at your
+ *  option) any later version.
+ *  
+ *  This program 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 General Public License
+ *  for more details.
+ *  
+ *  You should have received a copy of the GNU General Public License along
+ *  with this program. If not, see <http://www.gnu.org/licenses/>.
+ *  
+*/
+
+#include "Yara_native.h"
 #include <strings.h>
 #include <stdlib.h>
 
 VALUE class_Match = Qnil;
+
 VALUE class_MatchString = Qnil;
 
 const char * SCAN_ERRORS[] = {
@@ -38,7 +59,6 @@ const char * SCAN_ERRORS[] = {
   "incorrect external variable type",
 };
 
-
 typedef struct {
   VALUE rule;
   VALUE namespace;
@@ -53,7 +73,7 @@ typedef struct {
   VALUE buffer;
 } match_string;
 
-VALUE 
+static VALUE 
 MatchString_NEW(int offset, char *ident, char *buf, size_t buflen) {
   match_string *ms;
 
@@ -66,7 +86,7 @@ MatchString_NEW(int offset, char *ident, char *buf, size_t buflen) {
   ms->identifier  = rb_obj_freeze(rb_str_new2(ident));
   ms->buffer      = rb_obj_freeze(rb_str_new(buf, buflen));
 
-  return rb_obj_freeze(Data_Wrap_Struct(class_MatchString, 0, 0, ms));
+  return rb_obj_freeze(Data_Wrap_Struct(class_MatchString, 0, free, ms));
 }
 
 int 
@@ -104,7 +124,11 @@ Match_NEW_from_rule(RULE *rule, unsigned char *buffer, VALUE *match) {
     if (string->flags & STRING_FLAGS_FOUND) {
       m = string->matches;
       while (m) {
-       rb_ary_push(mi->strings, MatchString_NEW(m->offset, string->identifier, buffer + m->offset, m->length));
+       rb_ary_push(mi->strings, 
+           MatchString_NEW(m->offset, 
+             string->identifier, 
+             buffer + m->offset, 
+             m->length));
         m = m->next;
       }
     }
@@ -114,75 +138,168 @@ Match_NEW_from_rule(RULE *rule, unsigned char *buffer, VALUE *match) {
 
   meta = rule->meta_list_head;
   while(meta) {
-    // ... TODO
+    if (meta->type == META_TYPE_INTEGER) {
+      rb_hash_aset(mi->meta, 
+          rb_str_new2(meta->identifier), 
+          INT2NUM(meta->integer));
+    }
+    else if (meta->type == META_TYPE_BOOLEAN) {
+      rb_hash_aset(mi->meta, 
+          rb_str_new2(meta->identifier), 
+          ((meta->boolean) ? Qtrue : Qfalse));
+    }
+    else {
+      rb_hash_aset(mi->meta, 
+          rb_str_new2(meta->identifier), 
+          rb_obj_freeze(rb_str_new2(meta->string)));
+    }
+
     meta = meta->next;
   }
   rb_obj_freeze(mi->meta);
 
-  *(match) = rb_obj_freeze(Data_Wrap_Struct(class_Match, 0, 0, mi));
+  *(match) = rb_obj_freeze(Data_Wrap_Struct(class_Match, 0, free, mi));
 
   return 0;
 }
 
-VALUE match_rule(VALUE self) {
+/* 
+ * Document-method: rule
+ *
+ * call-seq:
+ *      match.rule() -> String
+ *
+ * Returns the rule identifier string for this match.
+ */
+static VALUE match_rule(VALUE self) {
   match_info *mi;
   Data_Get_Struct(self, match_info, mi);
   return mi->rule;
 }
 
-VALUE match_namespace(VALUE self) {
+/* 
+ * Document-method: namespace
+ *
+ * call-seq:
+ *      match.namespace() -> String
+ *
+ * Returns the namespace for this match.
+ */
+static VALUE match_namespace(VALUE self) {
   match_info *mi;
   Data_Get_Struct(self, match_info, mi);
   return mi->namespace;
 }
 
-VALUE match_tags(VALUE self) {
+/* 
+ * Document-method: tags
+ *
+ * call-seq:
+ *      match.tags() -> Array
+ *
+ * Returns an array of tag Strings for this match.
+ */
+static VALUE match_tags(VALUE self) {
   match_info *mi;
   Data_Get_Struct(self, match_info, mi);
   return mi->tags;
 }
 
-VALUE match_strings(VALUE self) {
+/* 
+ * Document-method: strings
+ *
+ * call-seq:
+ *      match.strings() -> Array
+ *
+ * Returns an array of MatchString objects for this match.
+ */
+static VALUE match_strings(VALUE self) {
   match_info *mi;
   Data_Get_Struct(self, match_info, mi);
   return mi->strings;
 }
 
-VALUE match_meta(VALUE self) {
+/* 
+ * Document-method: meta
+ *
+ * call-seq:
+ *      match.meta() -> Hash
+ *
+ * Returns a hash of metadata for the match object.
+ */
+static VALUE match_meta(VALUE self) {
   match_info *mi;
   Data_Get_Struct(self, match_info, mi);
   return mi->meta;
 }
 
-VALUE matchstring_identifier(VALUE self) {
+/* 
+ * Document-method: identifier
+ *
+ * call-seq:
+ *      matchstring.identifier() -> String
+ *
+ * Returns the identification label for the string.
+ */
+static VALUE matchstring_identifier(VALUE self) {
   match_string *ms;
   Data_Get_Struct(self, match_string, ms);
   return ms->identifier;
 }
 
-VALUE matchstring_offset(VALUE self) {
+/* 
+ * Document-method: offset
+ *
+ * call-seq:
+ *      matchstring.offset() -> fixnum
+ *
+ * Returns the offset where the match occurred.
+ */
+static VALUE matchstring_offset(VALUE self) {
   match_string *ms;
   Data_Get_Struct(self, match_string, ms);
   return ms->offset;
 }
 
-VALUE matchstring_buffer(VALUE self) {
+/* 
+ * Document-method: buffer
+ *
+ * call-seq:
+ *      matchstring.buffer() -> String
+ *
+ * Returns the data matched.
+ */
+static VALUE matchstring_buffer(VALUE self) {
   match_string *ms;
   Data_Get_Struct(self, match_string, ms);
   return ms->buffer;
 }
 
-
 void 
-init_match(VALUE rb_ns) {
-  class_Match = rb_define_class_under(rb_ns, "Match", rb_cObject);
+init_Match() {
+  VALUE module_Yara = rb_define_module("Yara");
+
+/*
+ * Document-class: Yara::Match
+ *
+ * Encapsulates a match object returned from Yara::Rules#scan_string or 
+ * Yara::Rules#scan_file. A Match contains one or more MatchString objects.
+ */
+  class_Match = rb_define_class_under(module_Yara, "Match", rb_cObject);
   rb_define_method(class_Match, "rule", match_rule, 0);
   rb_define_method(class_Match, "namespace", match_namespace, 0);
   rb_define_method(class_Match, "tags", match_tags, 0);
   rb_define_method(class_Match, "strings", match_strings, 0);
   rb_define_method(class_Match, "meta", match_meta, 0);
 
-  class_MatchString = rb_define_class_under(rb_ns, "MatchString", rb_cObject);
+
+/*
+ * Document-class: Yara::MatchString
+ *
+ * Encapsulates an individual matched string location. One or more of these
+ * will be available from a Match object.
+ */
+  class_MatchString = rb_define_class_under(module_Yara, "MatchString", rb_cObject);
   rb_define_method(class_MatchString, "identifier", matchstring_identifier, 0);
   rb_define_method(class_MatchString, "offset", matchstring_offset, 0);
   rb_define_method(class_MatchString, "buffer", matchstring_buffer, 0);

data/ext/yara_native/Match.h

@@ -1,20 +1,36 @@
+/*
+ *  yara-ruby - Ruby bindings for the yara malware analysis library.
+ *  Eric Monti
+ *  Copyright (C) 2011 Trustwave Holdings
+ *  
+ *  This program is free software: you can redistribute it and/or modify it 
+ *  under the terms of the GNU General Public License as published by the 
+ *  Free Software Foundation, either version 3 of the License, or (at your
+ *  option) any later version.
+ *  
+ *  This program 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 General Public License
+ *  for more details.
+ *  
+ *  You should have received a copy of the GNU General Public License along
+ *  with this program. If not, see <http://www.gnu.org/licenses/>.
+ *  
+*/
+
 #ifndef RB_MATCH_H_GUARD
 #define RB_MATCH_H_GUARD
 
 #include "ruby.h"
 #include <yara.h>
 
-extern VALUE class_Match;
-extern VALUE class_MatchString;
-
-extern void 
-init_match(VALUE ruby_namespace);
-
 extern int
 Match_NEW_from_rule(RULE * rule, unsigned char * buffer, VALUE * match);
 
 extern const char * SCAN_ERRORS[];
 
+void init_Match();
+
 #define MAX_SCAN_ERROR 29
 
 #endif

data/ext/yara_native/Rules.c

@@ -1,9 +1,28 @@
-#include "errors.h"
-#include "Rules.h"
+/*
+ *  yara-ruby - Ruby bindings for the yara malware analysis library.
+ *  Eric Monti
+ *  Copyright (C) 2011 Trustwave Holdings
+ *  
+ *  This program is free software: you can redistribute it and/or modify it 
+ *  under the terms of the GNU General Public License as published by the 
+ *  Free Software Foundation, either version 3 of the License, or (at your
+ *  option) any later version.
+ *  
+ *  This program 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 General Public License
+ *  for more details.
+ *  
+ *  You should have received a copy of the GNU General Public License along
+ *  with this program. If not, see <http://www.gnu.org/licenses/>.
+ *  
+*/
+
 #include "Match.h"
+#include "Yara_native.h"
 #include <stdio.h>
 
-static VALUE class_Rules = Qnil;
+VALUE class_Rules = Qnil;
 
 void rules_mark(YARA_CONTEXT *ctx) { }
 
@@ -17,6 +36,19 @@ VALUE rules_allocate(VALUE klass) {
   return Data_Wrap_Struct(klass, rules_mark, rules_free, ctx);
 }
 
+/* 
+ * Document-method: compile_file
+ *
+ * call-seq:
+ *      rules.compile_file(filename) -> nil
+ *
+ * Compiles rules taken from a file by its filename. This method
+ * can be called more than once using multiple rules strings and
+ * can be used in combination with compile_file.
+ *
+ * To avoid namespace conflicts, you can use set_namespace
+ * before compiling rules.
+ */
 VALUE rules_compile_file(VALUE self, VALUE rb_fname) {
   FILE * file;
   char * fname;
@@ -43,6 +75,19 @@ VALUE rules_compile_file(VALUE self, VALUE rb_fname) {
   }
 }
 
+/* 
+ * Document-method: compile_string
+ *
+ * call-seq:
+ *      rules.compile_string(rules_string) -> nil
+ *
+ * Compiles rules taken from a ruby string. This method
+ * can be called more than once using multiple rules strings
+ * and can be used in combination with compile_file.
+ *
+ * To avoid namespace conflicts, you can use set_namespace
+ * before compiling rules.
+ */
 VALUE rules_compile_string(VALUE self, VALUE rb_rules) {
   YARA_CONTEXT *ctx;
   char *rules;
@@ -60,13 +105,29 @@ VALUE rules_compile_string(VALUE self, VALUE rb_rules) {
   return Qtrue;
 }
 
+/* 
+ * Document-method: weight
+ *
+ * call-seq:
+ *      rules.weight() -> fixnum
+ *
+ * Returns a weight value for the compiled rules.
+ */
+
 VALUE rules_weight(VALUE self) {
   YARA_CONTEXT *ctx;
   Data_Get_Struct(self, YARA_CONTEXT, ctx);
   return INT2NUM(yr_calculate_rules_weight(ctx));
 }
 
-
+/* 
+ * Document-method: current_namespace
+ *
+ * call-seq:
+ *      rules.current_namespace() -> String
+ *
+ * Returns the name of the currently active namespace.
+ */
 VALUE rules_current_namespace(VALUE self) {
   YARA_CONTEXT *ctx;
   Data_Get_Struct(self, YARA_CONTEXT, ctx);
@@ -76,6 +137,14 @@ VALUE rules_current_namespace(VALUE self) {
     return Qnil;
 }
 
+/* 
+ * Document-method: namespaces
+ *
+ * call-seq:
+ *      rules.namespaces() -> Array
+ *
+ * Returns the namespaces available in this rules context.
+ */
 VALUE rules_namespaces(VALUE self) {
   YARA_CONTEXT *ctx;
   NAMESPACE *ns;
@@ -102,6 +171,18 @@ NAMESPACE * find_namespace(YARA_CONTEXT *ctx, const char *name) {
   return (NAMESPACE*) NULL;
 }
 
+/* 
+ * Document-method: set_namespace
+ *
+ * call-seq:
+ *      rules.set_namespace(name) -> nil
+ *
+ * Sets the current namespace to the given name. If the namespace
+ * does not yet exist it is added.
+ *
+ * To avoid namespace conflicts, you can use set_namespace
+ * before compiling rules.
+ */
 VALUE rules_set_namespace(VALUE self, VALUE rb_namespace) {
   YARA_CONTEXT *ctx;
   NAMESPACE *ns = NULL;
@@ -139,7 +220,15 @@ scan_callback(RULE *rule, unsigned char *buffer, unsigned int buffer_size, void
   return match_ret;
 }
 
-
+/* 
+ * Document-method: scan_file
+ *
+ * call-seq:
+ *      rules.scan_file(filename) -> nil
+ *
+ * Scans a file using the compiled rules supplied
+ * with either compile_file or compile_string (or both).
+ */
 VALUE rules_scan_file(VALUE self, VALUE rb_fname) {
   YARA_CONTEXT *ctx;
   VALUE results;
@@ -161,6 +250,16 @@ VALUE rules_scan_file(VALUE self, VALUE rb_fname) {
   return results;
 }
 
+
+/* 
+ * Document-method: scan_file
+ *
+ * call-seq:
+ *      rules.scan_string(data) -> nil
+ *
+ * Scans a ruby string using the compiled rules supplied
+ * with either compile_file or compile_string (or both).
+ */
 VALUE rules_scan_string(VALUE self, VALUE rb_dat) {
   YARA_CONTEXT *ctx;
   VALUE results;
@@ -184,9 +283,16 @@ VALUE rules_scan_string(VALUE self, VALUE rb_dat) {
   return results;
 }
 
-void init_rules(VALUE rb_ns) {
+/*
+ * Document-class: Yara::Rules
+ *
+ * Encapsulates a Yara context against which you can compile rules and
+ * scan inputs.
+ */
+void init_Rules() {
+  VALUE module_Yara = rb_define_module("Yara");
 
-  class_Rules = rb_define_class_under(rb_ns, "Rules", rb_cObject);
+  class_Rules = rb_define_class_under(module_Yara, "Rules", rb_cObject);
   rb_define_alloc_func(class_Rules, rules_allocate);
 
   rb_define_method(class_Rules, "compile_file", rules_compile_file, 1);
@@ -197,7 +303,5 @@ void init_rules(VALUE rb_ns) {
   rb_define_method(class_Rules, "set_namespace", rules_set_namespace, 1);
   rb_define_method(class_Rules, "scan_file", rules_scan_file, 1);
   rb_define_method(class_Rules, "scan_string", rules_scan_string, 1);
-
-  init_match(rb_ns);
 }