diff --git a/userspace/libhawk/README.md b/userspace/libhawk/README.md
new file mode 100644
index 00000000..acee1bf8
--- /dev/null
+++ b/userspace/libhawk/README.md
@@ -0,0 +1,80 @@
+# Libhawk
+
+Libhawk is a plugin system that can be used to enrich Falco
+functionalities via external, user-defined libraries.
+
+## Glossary:
+
+- library: a bundle (e.g: an ELF shared library) containing one or more plugins
+- plugin: an hawk plugin. Libraries can register one or more plugins using the `HAWK_REGISTER_PLUGIN` macro
+- plugin function: a specific function inside the plugin definition of each plugin. `hawk_init`, `hawk_destroy`
+
+## Plugin definitions and lifecycle
+
+Plugins are all loaded when Falco starts.
+Falco provides a default plugin for the main functionalities.
+
+### hawk_init
+On start, the `hawk_init` function of every plugin is called.
+You can use that function to create any resource you might need
+for your plugin's lifecycle.
+
+### hawk_destroy
+
+When Falco is stopped, the `hawk_destroy` p
+
+### hawk_watch_rules
+
+TODO: explain that only one at time can be done and how to configure. This can be
+explained once we have the plugin configuration code done.
+
+
+## Plugin loading
+
+TODO, describe how to dynamically load a plugin.
+This can be explained once this feature is developed.
+
+## Plugin configuration
+
+TODO
+This can be explained once this feature is developed.
+
+## Plugin example
+
+A plugin can define one or more definitions.
+
+Here's an example of plugin that is registered and defines
+`hawk_init`, `hawk_destroy` and `hawk_watch_rules`
+
+```c
+#include "hawk.h"
+
+void hawk_init() { printf("hawk_example init!\n"); }
+
+void hawk_destroy() {printf("hawk example destroy\n");}
+
+void hawk_watch_rules(hawk_watch_rules_cb cb, hawk_engine *engine) {
+ printf("loading rules\n");
+ cb("", engine); // todo: pass the rules here, this is empty
+}
+
+hawk_plugin_definition plugin_definition = {
+ .hawk_init = &hawk_init,
+ .hawk_destroy = &hawk_destroy,
+ .hawk_watch_rules = &hawk_watch_rules,
+};
+
+HAWK_REGISTER_PLUGIN(hawk_example_c, plugin_definition)
+```
+
+To compile the plugin, save it in a file `plugin.c` and then:
+
+```bash
+FALCO=/source/falco
+gcc -o libhawk.so -fPIC -shared -I$FALCO/userspace/libhawk plugin.c
+```
+
+Remember to change the `FALCO` variable to point to where you have the Falco sources.
+
+This should produce shared object called `libhawk.so`, you can use that to load the plugin in Falco.
+See the [Plugin loading](#plugin-loading) section.
diff --git a/userspace/libhawk/exception.h b/userspace/libhawk/exception.h
index 9253a4f2..e4f8f057 100644
--- a/userspace/libhawk/exception.h
+++ b/userspace/libhawk/exception.h
@@ -14,10 +14,24 @@ public:
std::runtime_error(message) {}
};
-class hawk_plugin_exception: public hawk_exception
+class hawk_plugin_exception : public hawk_exception
{
public:
hawk_plugin_exception(const std::string& plugin_name, const std::string& message):
hawk_exception("plugin: " + plugin_name + ", error: " + message) {}
};
+
+class hawk_library_exception : public hawk_exception
+{
+public:
+ hawk_library_exception(const std::string& message):
+ hawk_exception(message) {}
+};
+
+class hawk_library_load_exception : public hawk_library_exception
+{
+ public:
+ hawk_library_load_exception(const std::string&library_name, const std::string&message):
+ hawk_library_exception("library loading error, library: " + library_name + " error: " + message) {}
+};
} // namespace libhawk
diff --git a/userspace/libhawk/hawk.h b/userspace/libhawk/hawk.h
index 1e8c000c..1de1ad4b 100644
--- a/userspace/libhawk/hawk.h
+++ b/userspace/libhawk/hawk.h
@@ -1,6 +1,7 @@
#ifndef HAWK_H
#define HAWK_H
+// TODO(fntlnz): decide what to do with versioning here
#define HAWK_VERSION_CODE 0x000001
#define HAWK_VERSION_BITS(x, y, z) ((x) << 16 | (y) << 8 | (z))
#define HAWK_AT_LEAST_VERSION(x, y, z) \
diff --git a/userspace/libhawk/library.cpp b/userspace/libhawk/library.cpp
new file mode 100644
index 00000000..4d73534c
--- /dev/null
+++ b/userspace/libhawk/library.cpp
@@ -0,0 +1,34 @@
+/*
+Copyright (C) 2020 The Falco Authors.
+
+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.
+*/
+
+#include "library.h"
+#include "exception.h"
+
+#include
+
+libhawk::library::library(const std::string &filename) : m_library_filename(filename) {};
+
+bool libhawk::library::load()
+{
+ void *handler = nullptr;
+ handler = dlopen(m_library_filename.c_str(), RTLD_NOW);
+ if (!handler) {
+ std::string errmsg(dlerror());
+ throw hawk_library_load_exception(m_library_filename, errmsg);
+ }
+ //todo(fntlnz): need to store the handler or anything to use the library?
+ return (handler != nullptr);
+}
diff --git a/userspace/libhawk/library.h b/userspace/libhawk/library.h
new file mode 100644
index 00000000..3dd74222
--- /dev/null
+++ b/userspace/libhawk/library.h
@@ -0,0 +1,31 @@
+/*
+Copyright (C) 2020 The Falco Authors.
+
+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.
+*/
+
+#pragma once
+
+#include
+namespace libhawk
+{
+class library
+{
+public:
+ library(const std::string &filename);
+ bool load();
+ ~library();
+private:
+ std::string m_library_filename;
+};
+}; // namespace libhawk