Assessment template

Prepared by: <name> (@add-link-to-your-github-id)

Date: 2021-mm-dd

Introduction

This document assesses the quality and completeness of a project's documentation and website (if present).

This document:

• Measures existing documentation quality against the CNCF’s standards
• Recommends specific and general improvements
• Provides examples of great documentation as reference
• Identifies key improvements with the largest return on investment

How this document works

The assessment is divided into three sections:

• Project documentation: for end users of the project; aimed at people who intend to use it
• Contributor documentation: for new and existing contributors to the project
• Website: branding, website structure, and maintainability

Each section rates content based on different criteria.

Project documentation

Criteria	1	2	3	4	5
Information architecture
New user content
Content maintainability
Content creation processes

Scale:

• 1 = (Is not present or requires significant work)
• 3 = (Is present, but needs work)
• 5 = (Is executed extremely well or no improvement required)

Comments

Provide comments for each rating above, 1-2 sentences max, bullet point list

• Information architecture

• New user content

  • Falco's getting started is used as an example for new user content in the Techdocs assessment!
    • I'm not sure it's up to date, I've tried setting it up following the getting started and ran into errors

Recommendations

Provide a list of recommendations to improve in this area

Contributor documentation

Criteria	1	2	3	4	5
Communication methods documented
Beginner friendly issue backlog
“New contributor” getting started content
Project governance documentation

Scale:

• 1 = (Is not present or requires significant work)
• 3 = (Is present, but needs work)
• 5 = (Is executed extremely well or no improvement required)

Comments

Provide comments for each rating above, 1-2 sentences max, bullet point list

Recommendations

Provide a list of recommendations to improve in this area

Website

Criteria	1	2	3	4	5
Single-source for all files
Meets min website req. (for maturity level)
Branding and design
Case studies/social proof
Maintenance planning
A11y plan & implementation
Mobile-first plan & impl.
HTTPS access & HTTP redirect
Google Analytics 4 for production only
Indexing allowed for production server only
Intra-site / local search
Account custodians are documented

Scale:

• 1 = (Is not present or requires significant work)
• 3 = (Is present, but needs work)
• 5 = (Is executed extremely well or no improvement required)

Comments

Provide comments for each rating above, 1-2 sentences max, bullet point list
Include a list of the top 404s, as reported through analytics or a search console.

Recommendations

Provide a list of recommendations to improve in this area

Recommendations

From the recommendations above, lis the top 1-3 concerns for this particular project and expand on them in enough detail that you could either:
- Pass the work off to a contractor or other member of the CNCF techdocs team
- Write a GitHub issue for the project team and place it in the backlog and someone not involved in the docs assessment process could execute on it

Notes

Friction log

Attempting to get started -

https://github.com/falcosecurity/falco/issues/1024 should be reopened?

1. VMware fusion - ubuntu

Getting started

• I'm not sure the Getting started "Try Falco on Ubuntu" instructions are up to date
  • https://falco.org/docs/getting-started/try-falco/try-falco-on-ubuntu/
• Tried the regular install instructions and ran into issues as well
  • https://falco.org/docs/getting-started/installation/
• When I get to the 'Configure the apt repository' step I always get a Permssion denied error
  (/etc/apt/sources.list.d/falcosecurity.list)
• also tried several to use the Vagrant file supplied, but ran into the same issue in the end.

1. Docker

base system: MacBook Pro 14-inch, 2021 Apple M1 Pro, macOS 13.4.1
docker desktop v 4.17.0

https://falco.org/docs/getting-started/running/#docker

Recommendad least privileged instructions fail at:

$ docker run --rm -i -t \
    --privileged \
    -v /root/.falco:/root/.falco \
    -v /proc:/host/proc:ro \
    -v /boot:/host/boot:ro \
    -v /lib/modules:/host/lib/modules \
    -v /usr:/host/usr:ro \
    -v /etc:/host/etc:ro \
    falcosecurity/falco-driver-loader:latest

docker: Error response from daemon: Mounts denied:
The path /root/.falco is not shared from the host and is not known to Docker.
You can configure shared paths from Docker -> Preferences... -> Resources -> File Sharing.
See https://docs.docker.com/desktop/mac for more info.
ERRO[0000] error waiting for container:

1. Running Falco on Apple Silicon

base system: MacBook Pro 14-inch, 2021 Apple M1 Pro, macOS 13.4.1

https://falco.org/blog/falco-apple-silicon/

Fails at: $ sudo falco-driver-loader bpf

Blog article should also provide cleanup instructions.

$ sudo falco-driver-loader bpf
* Running falco-driver-loader for: falco version=0.35.1, driver version=5.0.1+driver, arch=aarch64, kernel release=6.3.8-200.fc38.aarch64, kernel version=1
* Running falco-driver-loader with: driver=bpf, compile=yes, download=yes
* Filename 'falco_fedora_6.3.8-200.fc38.aarch64_1.o' is composed of:
 - driver name: falco
 - target identifier: fedora
 - kernel release: 6.3.8-200.fc38.aarch64
 - kernel version: 1
* Trying to download a prebuilt eBPF probe from https://download.falco.org/driver/5.0.1%2Bdriver/aarch64/falco_fedora_6.3.8-200.fc38.aarch64_1.o
curl: (22) The requested URL returned error: 404
Unable to find a prebuilt falco eBPF probe
* Trying to compile the eBPF probe (falco_fedora_6.3.8-200.fc38.aarch64_1.o)
warning: the compiler differs from the one used to build the kernel
  The kernel was built by: gcc (GCC) 13.1.1 20230511 (Red Hat 13.1.1-2)
  You are using:           gcc (GCC) 13.1.1 20230614 (Red Hat 13.1.1-4)
In file included from /usr/src/falco-5.0.1+driver/bpf/probe.c:25:
In file included from /usr/src/falco-5.0.1+driver/bpf/filler_helpers.h:14:
In file included from ./include/net/sock.h:46:
In file included from ./include/linux/netdevice.h:38:
In file included from ./include/net/net_namespace.h:43:
In file included from ./include/linux/skbuff.h:17:
In file included from ./include/linux/bvec.h:10:
In file included from ./include/linux/highmem.h:8:
In file included from ./include/linux/cacheflush.h:5:
In file included from ./arch/arm64/include/asm/cacheflush.h:11:
In file included from ./include/linux/kgdb.h:19:
In file included from ./include/linux/kprobes.h:30:
./include/linux/freelist.h:88:48: warning: passing 'unsigned int *' to parameter of type 'int *' converts between pointers to integer types with different sign [-Wpointer-sign]
                    !atomic_try_cmpxchg_acquire(&head->refs, &refs, refs+1)) {
                                                             ^~~~~
./include/linux/atomic/atomic-instrumented.h:539:46: note: passing argument to parameter 'old' here
atomic_try_cmpxchg_acquire(atomic_t *v, int *old, int new)
                                             ^
In file included from /usr/src/falco-5.0.1+driver/bpf/probe.c:26:
/usr/src/falco-5.0.1+driver/bpf/fillers.h:6343:76: error: no member named 'cap' in 'kernel_cap_t'
        res = bpf_push_u64_to_ring(data, capabilities_to_scap(((unsigned long)cap.cap[1] << 32) | cap.cap[0]));
                                                                              ~~~ ^
/usr/src/falco-5.0.1+driver/bpf/fillers.h:6343:96: error: no member named 'cap' in 'kernel_cap_t'
        res = bpf_push_u64_to_ring(data, capabilities_to_scap(((unsigned long)cap.cap[1] << 32) | cap.cap[0]));
                                                                                                  ~~~ ^
/usr/src/falco-5.0.1+driver/bpf/fillers.h:6348:76: error: no member named 'cap' in 'kernel_cap_t'
        res = bpf_push_u64_to_ring(data, capabilities_to_scap(((unsigned long)cap.cap[1] << 32) | cap.cap[0]));
                                                                              ~~~ ^
/usr/src/falco-5.0.1+driver/bpf/fillers.h:6348:96: error: no member named 'cap' in 'kernel_cap_t'
        res = bpf_push_u64_to_ring(data, capabilities_to_scap(((unsigned long)cap.cap[1] << 32) | cap.cap[0]));
                                                                                                  ~~~ ^
/usr/src/falco-5.0.1+driver/bpf/fillers.h:6353:76: error: no member named 'cap' in 'kernel_cap_t'
        res = bpf_push_u64_to_ring(data, capabilities_to_scap(((unsigned long)cap.cap[1] << 32) | cap.cap[0]));
                                                                              ~~~ ^
/usr/src/falco-5.0.1+driver/bpf/fillers.h:6353:96: error: no member named 'cap' in 'kernel_cap_t'
        res = bpf_push_u64_to_ring(data, capabilities_to_scap(((unsigned long)cap.cap[1] << 32) | cap.cap[0]));
                                                                                                  ~~~ ^
1 warning and 6 errors generated.
make[2]: *** [/usr/src/falco-5.0.1+driver/bpf/Makefile:54: /usr/src/falco-5.0.1+driver/bpf/probe.o] Error 1
make[1]: *** [Makefile:2037: /usr/src/falco-5.0.1+driver/bpf] Error 2
make: *** [Makefile:38: all] Error 2
mv: cannot stat '/usr/src/falco-5.0.1+driver/bpf/probe.o': No such file or directory
Unable to load the falco eBPF probe

Solved by

1. ensuring I was running fedora 36

then I ran into

$ sudo systemctl enable --now falco
Failed to enable unit: Unit file falco.service does not exist.

which I solved by:
sudo /usr/bin/falco-driver-loader

Now I can run falco manually (tho i can't seem to add it to a service, so i need to run it each time the system boots)

sudo /usr/bin/falco-driver-loader
sudo /usr/bin/falco