Fixes + comments & documentation. Can now be used as a template

* adapted to use the new api layout of ARTist
* updated with changed signatures from ARTist (updated module-sdk)
* added comments and documentation
* created 2 artist passes to showcase different use cases and existing boilerplate code, one injection pass (HInjectionArtist) and one basic pass (HArtist)
* added small filter to only accept non-static methods (and skip the majority to not bloat logcat too much)

Author: schrnz

CMakeLists.txt

@@ -6,10 +6,12 @@ set(CMAKE_CXX_STANDARD 11)
 add_executable(template_module
         src/module.cc
         src/module.h
-        src/instrumentation_pass.cc
-        src/instrumentation_pass.h
+        src/template_injection_pass.cc
+        src/template_injection_pass.h
+        src/template_basic_pass.cc
+        src/template_basic_pass.h
         src/codelib.cc
-        src/codelib.h)
+        src/codelib.h src/simple_method_filter.cc src/simple_method_filter.h)
 
 target_include_directories(template_module PUBLIC
         /opt/artist-sdk/include/external/valgrind

Manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest_version": 1,
-  "package_name": "com.example.module",
-  "name": "Artist Module",
-  "description": "This a template module.",
-  "author": "John Doe <[email protected]>",
+  "package_name": "saarland.cispa.artist.module.template",
+  "name": "Template Module",
+  "description": "This a template module, all functionality is purely educational. If you want ",
+  "author": "Parthipan Ramesh <[email protected]>, Oliver Schranz <[email protected]>",
   "version": 1
 }

codelib.apk

@@ -16,29 +16,31 @@
  * limitations under the License.
  *
  * @author "Parthipan Ramesh <[email protected]>"
+ * @author "Oliver Schranz <[email protected]>"
  *
  */
 
 #include "codelib.h"
 
-unordered_set<string> &ModuleCodeLib::getMethods() const {
-    // TODO: implement methods like example below
-    // static string instanceField = "Lsaarland/cispa/artist/codelib/CodeLib;traceLog()V";
-    // static unordered_set<string> methods({instanceField});
-    static unordered_set<string> methods({});
-    return methods;
+const std::string TemplateCodeLib::INJECTION_ARTIST_TARGET("Lsaarland/cispa/artist/codelib/CodeLib;injectionArtistTarget(I)V");
+const std::string TemplateCodeLib::BASIC_ARTIST_TARGET("Lsaarland/cispa/artist/codelib/CodeLib;basicArtistTarget(ILjava/lang/Object;)V");
+
+
+unordered_set<string> &TemplateCodeLib::getMethods() const {
+  // here we expose the signatures of codelib methods that are meant to be used from ARTist
+  static unordered_set<string> methods({INJECTION_ARTIST_TARGET, BASIC_ARTIST_TARGET});
+  return methods;
 }
 
-string &ModuleCodeLib::getInstanceField() const {
-    // TODO: implement instance fields like example below
-    // static string instanceField = "Lsaarland/cispa/artist/codelib/CodeLib;INSTANCE";
-    static string instanceField;
-    return instanceField;
+string &TemplateCodeLib::getInstanceField() const {
+  // here we expose the static field with our singleton instance. This will be used by ARTist to obtain an instance
+  // of the codelib to call methods on it.
+  static string instanceField = "Lsaarland/cispa/artist/codelib/CodeLib;INSTANCE";
+  return instanceField;
 }
 
-string &ModuleCodeLib::getCodeClass() const {
-    // TODO: implement code class like example below
-    // static string codeClass = "Lsaarland/cispa/artist/codelib/CodeLib;";
-    static string codeClass;
-    return codeClass;
+string &TemplateCodeLib::getCodeClass() const {
+  // here we expose the codelib's java class to be able to load it in ARTist
+  static string codeClass = "Lsaarland/cispa/artist/codelib/CodeLib;";
+  return codeClass;
 }

src/codelib.cc

@@ -16,6 +16,7 @@
  * limitations under the License.
  *
  * @author "Parthipan Ramesh <[email protected]>"
+ * @author "Oliver Schranz <[email protected]>"
  *
  */
 
@@ -24,32 +25,36 @@
 
 #include <string>
 #include <unordered_set>
-#include <artist/env/codelib.h>
+#include <artist/api/modules/codelib.h>
 
 using std::string;
 using std::unordered_set;
 
 using art::CodeLib;
 
-class ModuleCodeLib : public CodeLib {
+class TemplateCodeLib : public CodeLib {
 public:
-    ModuleCodeLib() = default;
+  static const string INJECTION_ARTIST_TARGET;
+  static const string BASIC_ARTIST_TARGET;
 
-    ModuleCodeLib(const ModuleCodeLib &other) = default;
 
-    ModuleCodeLib(ModuleCodeLib &&other) = default;
+  TemplateCodeLib() = default;
 
-    ~ModuleCodeLib() override = default;
+    TemplateCodeLib(const TemplateCodeLib &other) = default;
 
-    ModuleCodeLib &operator=(const ModuleCodeLib &) = default;
+    TemplateCodeLib(TemplateCodeLib &&other) = default;
 
-    ModuleCodeLib &operator=(ModuleCodeLib &&) = default;
+    ~TemplateCodeLib() override = default;
+
+    TemplateCodeLib &operator=(const TemplateCodeLib &) = default;
+
+    TemplateCodeLib &operator=(TemplateCodeLib &&) = default;
 
     unordered_set<string> &getMethods() const override;
 
     string &getInstanceField() const override;
 
     string &getCodeClass() const override;
-};  // class ModuleCodeLib
+};  // class TemplateCodeLib
 
 #endif  // ART_MODULES_CODELIB_H_

src/codelib.h

@@ -16,33 +16,51 @@
  * limitations under the License.
  *
  * @author "Parthipan Ramesh <[email protected]>"
+ * @author "Oliver Schranz <[email protected]>"
  *
  */
 
-#include <artist/filtering/method_name_filters.h>
+#include <artist/api/filtering/method_name_filters.h>
 
 #include "module.h"
-#include "instrumentation_pass.h"
+//#include "template_basic_pass.h"
+#include "template_injection_pass.h"
 #include "codelib.h"
+#include "simple_method_filter.h"
 
 using std::make_shared;
 using std::unique_ptr;
 
-shared_ptr<HArtist> ArtistModule::createPass(const MethodInfo &method_info) const {
-    return make_shared<HModule>(method_info);
+using art::ModuleId;
+
+TemplateModule::TemplateModule(const shared_ptr<const art::FilesystemHelper> fs) : Module(fs) {}
+
+HArtist * TemplateModule::createPass(const MethodInfo &method_info) const {
+    // Due to the *clone bug* (https://github.com/Project-ARTist/ARTist/issues/10), we can only define one pass per
+    // module right now, but this will change as soon as this bug is resolved.
+  return new (method_info.GetGraph()->GetArena()) HTemplateInjectionArtist(method_info);
+//  return new (method_info.GetGraph()->GetArena()) HTemplateBasicArtist(method_info);
 }
 
-shared_ptr<const CodeLib> ArtistModule::createCodeLib() const {
-    return make_shared<ModuleCodeLib>();
+shared_ptr<const CodeLib> TemplateModule::createCodeLib() const {
+    return make_shared<TemplateCodeLib>();
 }
 
-// Possible MethodFilter: skip android support lib ui methods since they bloat up the log
-unique_ptr<Filter> ArtistModule::getMethodFilter() const {
-    const vector<const string> ui = {"android.support."};
-    return unique_ptr<Filter>(new art::BlacklistFilter(ui));
+
+// Here we can restrict for which methods our module should be executed.
+unique_ptr<Filter> TemplateModule::getMethodFilter() const {
+    // creating blacklists/whitelists for method names is straightforward:
+    // const vector<const string> ui = {"android.support."};
+    // return unique_ptr<Filter>(new MethodNameBlacklist(ui));
+
+    // but here we use a custom filter that only excepts non-static methods (and only a fragment of the others)
+    return unique_ptr<Filter>(new SimpleMethodFilter());
+}
+// the module factory
+extern "C" shared_ptr<Module> create(shared_ptr<const FilesystemHelper> fshelper) {
+    return make_shared<TemplateModule>(fshelper);
 }
 
-// the class factories
-extern "C" shared_ptr<art::Module> create() {
-    return make_shared<ArtistModule>();
+extern "C" ModuleId get_id() {
+  return "saarland.cispa.artist.module.template";
 }

src/instrumentation_pass.cc

@@ -16,27 +16,31 @@
  * limitations under the License.
  *
  * @author "Parthipan Ramesh <[email protected]>"
+ * @author "Oliver Schranz <[email protected]>"
  *
  */
 
 #ifndef  ART_MODULES__MODULE_H_
 #define  ART_MODULES__MODULE_H_
 
-#include <artist/modules/module.h>
+#include <artist/api/modules/module.h>
 
 using art::Module;
 using art::HArtist;
 using art::MethodInfo;
 using art::CodeLib;
 using art::Filter;
+using art::FilesystemHelper;
 
-class ArtistModule : public Module {
-    shared_ptr<HArtist> createPass(const MethodInfo &method_info) const OVERRIDE;
+class TemplateModule : public Module {
+  HArtist * createPass(const MethodInfo &method_info) const OVERRIDE;
 
-    shared_ptr<const CodeLib> createCodeLib() const OVERRIDE;
+  shared_ptr<const CodeLib> createCodeLib() const OVERRIDE;
 
 public:
-    unique_ptr<Filter> getMethodFilter() const OVERRIDE;
+  explicit TemplateModule(const shared_ptr<const FilesystemHelper> fs);
+
+  unique_ptr<Filter> getMethodFilter() const OVERRIDE;
 };
 
 #endif  // ART_MODULES__MODULE_H_

src/module.cc

@@ -0,0 +1,45 @@
+/**
+ * The ARTist Project (https://artist.cispa.saarland)
+ *
+ * Copyright (C) 2018 CISPA (https://cispa.saarland), Saarland University
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author "Oliver Schranz <[email protected]>"
+ *
+ */
+
+#include "simple_method_filter.h"
+
+int SimpleMethodFilter::MOD = 1000000;
+
+/**
+ * Simple filter implementation that rejects all static methods and for all others only accepts after seeing `MOD`
+ * methods. The reason is that in our (template) injection we write a lot to logcat and hence should avoid to inject
+ * calls to this method too often.
+ *
+ * @param info information & data about the currently compiled method
+ * @return
+ */
+bool SimpleMethodFilter::accept(const art::MethodInfo &info) {
+  if (info.IsStatic()) {
+    return false;
+  }
+
+  mtx.lock();
+  bool res =  count == 0;
+  count = (count + 1) % SimpleMethodFilter::MOD;
+  mtx.unlock();
+  return res;
+}
+

src/module.h

@@ -0,0 +1,47 @@
+/**
+ * The ARTist Project (https://artist.cispa.saarland)
+ *
+ * Copyright (C) 2018 CISPA (https://cispa.saarland), Saarland University
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author "Oliver Schranz <[email protected]>"
+ *
+ */
+
+
+#ifndef ART_MODULES__STATICMETHODFILTER_H
+#define ART_MODULES__STATICMETHODFILTER_H
+
+#include <artist/api/filtering/filter.h>
+
+using std::mutex;
+
+using art::Filter;
+
+class SimpleMethodFilter : public Filter {
+public:
+  SimpleMethodFilter() : count(0) {};
+
+  bool accept(const art::MethodInfo &info) override;
+private:
+  // after how many non-static methods we will accept one (restrict number of instrumented methods)
+  static int MOD;
+
+  // mutex for atomic `check and write` operation on `count`
+  mutex mtx;
+  // how many methods did we check already
+  int count;
+};
+
+#endif //ART_MODULES__STATICMETHODFILTER_H