docs: add basic docs data

.families.yaml

@@ -122,20 +122,22 @@ rootkits:
     chkrootkit:
       binary_path: chkrootkit
 
+# TODO: decide how to use them across families, probably
+# referencing them from here would be the simplest way.
 plugins:
   - name: binary-plugin
     type: binary
     path: path-to-binary
-    # config
+    # config: some config data
     # Note: communicates via CLI
   - name: container-plugin
     type: container
     # version: v1
     path: image-repo
-    # config
-    # Note: communicates via HTTP endpoint/socket
-  - name: grpc-plugin
-    type: grpc
+    # config: some config data, e.g. bootstrapping options, additional volumes, etc
+    # Note: communicates via embedded HTTP server via socket
+  - name: rest-plugin
+    type: rest-server
     path: http://localhost:1234
-    # config
-    # Note: this works by interacting with the HTTP server
+    # config: something to figure out?
+    # Note: communicates with the HTTP server directly

scanner/README.md

@@ -0,0 +1,29 @@
+## Pluggable scanners
+
+
+### Goals
+- standalone
+- quick to start
+- language-agnostic via client stubs for other languages
+- modular
+- scalable, albeit as a single service for now (no time to implement/rely on queues)
+- can be run as a container (kuberentes job or REST service), CLI command, or binary
+- can perform long running operations
+- replace current golang only approach for scanning
+- ...more things to capture here
+
+### Non-goals
+- durability, scans live only for the container lifetime
+  - SQLite DB can be exported as a file and reused, but did not try to make it work and probably will not to.
+  It will complicate more than benefit if done.
+- Replace centralized VMClarity DB for scanning results
+- ...more things to capture here
+
+
+## Brief overview
+Golang REST server implementation will be running across all scanner types (Go, Python, Rust, etc).
+Language-specific approaches will utilize the Go REST server as temporary DB and source of truth for scans (long running operations)
+and their results (scan findings).
+Other languages will only implement the scanner interface and interact with the REST server via client stubs (autogenerated with minimal changes) 
+that will be embedded into containers (MIGHT CHANGE).
+Use Golang scanner example to see how the new scanners will look like.

scanner/golang/example/README.md

@@ -2,3 +2,8 @@
 
 You only have to implement the files under `scanner` dir. 
 CIS Docker benchmark was taken as an example.
+
+Scanner main module is not done as it's importing Golang REST server code rather than running REST server (which is okay for now and provides the same experience).
+Ideally, we want to change that to client stub and replace the `server.go` to only use the client itself with reporting mechanism.
+The reason for the current approach is that I wanted to implement the job orchestrator/executor so that we can have a simple interface
+and be able to implement new scanners quickly.

scanner/golang/example/server.go

@@ -25,6 +25,8 @@ import (
 	"scanner/scanner"
 )
 
+// TODO(ramizpolic): change to use client stubs rather than REST server import
+
 func main() {
 	// Load components
 	config, err := NewConfig()