mirrors/opensnitch
1
0
Fork 0
mirror of https://github.com/evilsocket/opensnitch.git synced 2025-03-04 08:34:40 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Merge pull request #349 from themighty1/wiki

Browse source 
add wiki
This commit is contained in:
Gustavo Iñiguez Goia 2021-02-15 10:41:26 +01:00 • committed by GitHub
commit 3c87288914
Failed to generate hash of commit
19 changed files with 1322 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
.github/workflows/updatewiki.yml vendored Normal file
View file

@ -0,0 +1,32 @@
name: Update wiki
on:
push:
paths:
- 'wiki/**'
pull_request:
paths:
- 'wiki/**'
jobs:
job1:
name: Update wiki
runs-on: ubuntu-latest
steps:
- name: Clone opensnitch repo
uses: actions/checkout@v2
- name: Clone wiki repo and update
env:
ORG: "evilsocket"
REPO_SOURCE: "opensnitch"
REPO_DEST: "opensnitch.wiki"
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
GH_REPO_DEST="github.com/$ORG/$REPO_DEST.git"
git clone https://$GH_REPO_DEST
mv -f wiki/* $REPO_DEST/
cd $REPO_DEST
git config user.name "wiki auto updater"
git add .
git commit -m "updated after opensnitch repo commit $GITHUB_SHA"
git remote add origin-wiki "https://$ORG:$GITHUB_TOKEN@$GH_REPO_DEST"
git push origin-wiki master

3
wiki/Adding,-updating-and-installing-new-translations.md Normal file
View file

@ -0,0 +1,3 @@
Read all the information relative to GUI internazionalization here:
https://github.com/evilsocket/opensnitch/tree/master/ui/i18n

21
wiki/Building-packages-with-pbuilder.md Normal file
View file

@ -0,0 +1,21 @@
Using pbuilder is a fancy way of creating deb packages.
You just need to download the .dsc file:
> $ wget https://github.com/gustavo-iniguez-goya/opensnitch/releases/download/v1.0.0rc10/opensnitch_1.0.0rc10-1.dsc
Create the chroot environment:
```
$ sudo apt install qemu-static
$ sudo pbuilder create --architecture armhf --distribution sid --debootstrap qemu-debootstrap --basetgz /var/cache/pbuilder/sid-armhf.tgz
```
build the package using the pbuilder chroot:
> $ sudo pbuilder build --architecture armhf --basetgz /var/cache/pbuilder/sid-armhf.tgz --buildresult /tmp/rc10/pkgs opensnitch_1.0.0rc9-1.dsc
You can repeat the process for arm64, amd64, i386, etc..., and other distributions:
```
--distribution sid
--architecture armhf
```

80
wiki/Compilation.md Normal file
View file

@ -0,0 +1,80 @@
### Installation from sources
(tested on Debian sid and Ubuntu 20. It may fail on other distributions.)
Make sure you have a correctly configured **Go >= 1.13** environment (it also may work with >= 1.11), that the `$GOPATH` environment variable is defined and then:
```bash
# install dependencies
sudo apt-get install git golang libnetfilter-queue-dev libpcap-dev protobuf-compiler python3-pip pyqt5-dev-tools
go get github.com/golang/protobuf/protoc-gen-go
export GOPATH=~/go #you may want to change this if your Go directory is different
export PATH=$PATH:$GOPATH/bin
python3 -m pip install --user grpcio-tools
# clone the repository (ignore the message about no Go files being found)
go get github.com/gustavo-iniguez-goya/opensnitch
cd $GOPATH/src/github.com/gustavo-iniguez-goya/opensnitch
# compile && install
make
sudo make install
# enable opensnitchd as a systemd service and start the UI
sudo systemctl enable opensnitchd
sudo service opensnitchd start
opensnitch-ui
```
**Daemon**
The `daemon` is implemented in Go and needs to run as root in order to interact with the Netfilter packet queue, edit
iptables rules and so on, in order to compile it you will need to install the `protobuf-compiler`, `libpcap-dev` and `libnetfilter-queue-dev`
packages on your system, then just:
cd daemon
make
You can then install it as a systemd service by doing:
sudo make install
The new `opensnitchd` service will log messages to `/var/log/opensnitchd.log`, save the rules under `/etc/opensnitchd/rules` and connect to the default UI service socket `unix:///tmp/osui.sock`.
As of v1.0.0-rc2 version, it has been tested on Debian >= 8, Ubuntu >= 14, Fedora >= 23, MXLinux 19, Arch, and OpenSuse 15/Tumbleweed.
***
### UI
**Note:** If you run into troubles installing the UI from the sources, either use the deb/rpm packages to resolve the dependencies or install the needed packages from your distribution package manager (especially pyqt5).
The user interface is a Python 3 software running as a `gRPC` server on a unix socket, in order to install its dependencies type the following:
cd ui
sudo pip3 install -r requirements.txt
**Tip 1:** If pip fails installing pyqt5, try changing the pyqt5 version in `requirements.txt` to install pyqt5==5.10 or other version that work for you.
**Tip 2:** On newer distros, you may need to upgrade pip (`pip3 install --upgrade --user pip`) [#305](https://github.com/evilsocket/opensnitch/issues/305)
The UI is pip installable itself:
sudo pip3 install .
This will install the `opensnitch-ui` command on your system (you can auto startup it by `cp opensnitch_ui.desktop ~/.config/autostart/`).
***
### Running
Once you installed both the daemon and the UI, you can enable the `opensnitchd` service to run at boot time:
sudo systemctl enable opensnitchd
And run it with:
sudo service opensnitchd start
While the UI can be started just by executing the `opensnitch-ui` command.

58
wiki/Configurations.md Normal file
View file

@ -0,0 +1,58 @@
### Daemon configuration
Some default working options can be customized in the file _/etc/opensnitchd/default-config.json_:
```
{
"Server": {
"Address": "unix:///tmp/osui.sock",
"LogFile": "/var/log/opensnitchd.log"
},
"DefaultAction": "deny",
"DefaultDuration": "once",
"InterceptUnknown": true,
"ProcMonitorMethod": "proc",
"LogLevel": 1
}
```
* Address: Unix socket (unix:///tmp/osui.sock, the "unix:///" part is mandatory) or TCP socket (192.168.1.100:50051)
* DefaultAction: allow | deny
* DefaultDuration: once | always | until restart | 30s | 5m | 15m | 30m | 1h
* InterceptUnknown: true | false
- Block or allow connections whose process path has not been found.
* ProcMonitorMethod: proc | ftrace | audit
* LogLevel: 0 to 4 (debug, info, important, warning, error)
If you change the configuration or the rules under _/etc/opensnitchd/_, they'll be reloaded. No restart is needed.
**NOTE about _intercept_unknown_ option**: It was added when OpenSnitch used to miss a lot of connections (couldn't find pid/process in /proc). As of v1.0.0rc5 version, maybe it's safe to set it to false, and just let drop those unknown spare connections. It's up to you.
***
### GUI
By default OpenSnitch UI listen in a local Unix socket in /tmp/osui.sock.
In some distros, /tmp is cleared out every time in a while, so you're encouraged to change it to other location.
**Single UI with many computers**
Use --socket "[::]:50051" to have the UI use TCP instead of a Unix socket and run the daemon on another computer with -ui-socket "x.x.x.x:50051" (where x.x.x.x is the IP of the computer running the UI service).
`# /usr/bin/opensnitchd -rules-path /etc/opensnitchd/rules -ui-socket 172.17.0.1:50051`
`$ /usr/local/bin/opensnitch-ui --socket "[::]:50051"`
![image](https://user-images.githubusercontent.com/2742953/82752021-9d328380-9dbb-11ea-913e-80f7b551a6c7.png)
**Configuration**
The GUI saves the changes you make every time you resize the statistics window, or when answering a connection prompt dialog. It'll also remember which tab you clicked the last time.
The size of each column of each tab will also be saved.
It is saved under _$HOME/.config/opensnitch/settings.conf_, and it's handled by the GUI.
![image](https://user-images.githubusercontent.com/2742953/82752761-aa9e3c80-9dc0-11ea-90eb-992a99f0b878.png)
***

30
wiki/Cross-compilation.md Normal file
View file

@ -0,0 +1,30 @@
### Cross compiling the daemon for other architectures (arm)
The following steps are for compile OpenSnitch on _Debian testing_ for armhf. You may run into incompabilities on other distros (like Debian sid).
```
$ sudo dpkg --add-architecture armhf
$ sudo apt update
$ sudo apt install libnetfilter-queue-dev:armhf libmnl-dev:armhf
$ sudo apt install gcc-8-arm-linux-gnueabihf gcc-8-arm-linux-gnueabihf-base gcc-8-plugin-dev-arm-linux-gnueabi gcc-arm-linux-gnueabi
$ export CC=arm-linux-gnueabi-gcc
$ export CGO_LDFLAGS="-L/usr/lib/arm-linux-gnueabihf/"
$ GOOS=linux GOARM=7 GOARCH=arm CGO_ENABLED=1 PKG_CONFIG_PATH="/usr/lib/arm-linux-gnueabihf/pkgconfig/" go build -o opensnitchd-arm -x .
```
**arm64**
Discussion regarding running the daemon on arm64: [#18](https://github.com/gustavo-iniguez-goya/opensnitch/issues/18)
```
$ sudo dpkg --add-architecture arm64
$ sudo apt update
$ sudo apt install libnetfilter-queue-dev:arm64 libmnl-dev:arm64
$ apt install gccgo-aarch64-linux-gnu
$ export CC=aarch64-linux-gnu-gcc
$ export CGO_LDFLAGS="-L/usr/lib/aarch64-linux-gnu/"
$ GOOS=linux GOARCH=arm64 CGO_ENABLED=1 PKG_CONFIG_PATH="/usr/lib/aarch64-linux-gnu/pkgconfig/" go build -o opensnitchd-arm64 .
```
***

49
wiki/FAQs.md Normal file
View file

@ -0,0 +1,49 @@
**OpenSnitch displays too many dialogs to allow/deny connections**
Yes, it does. But only the first time it is used. Once you configure which processes/connections you want to allow/deny, you won't notice that it's running. Really.
In the future, maybe we add an option to queue events, and allow/deny them from the GUI applying th default configured action until further interaction from the user.
**Why Qt and not GTK?**
I tried, but for very fast updates it failed bad on my configuration (failed bad = SIGSEGV), moreover I find Qt5 layout system superior and easier to use.
**Why gRPC and not DBUS?**
The UI service is able to use a TCP listener instead of a UNIX socket, that means the UI service itself can be executed on any operating system, while receiving messages from a single local daemon instance or multiple instances from remote computers in the network, therefore DBUS would have made the protocol and logic uselessly GNU/Linux specific.
**Which connections does OpenSnitch intercept?**
We currently (>= v1.0.0-rc4) only intercept new connections (iptables/conntrack state NEW) of TCP, UDP and UDPLITE protocols, to/from any port.
**What means "intercept unknown connections" configuration option**
When a process establishes a new connection, we first receive the connection information (src/dst IP, src/dst port, but no PID, nor process command line/path). Thus, we try to get who created the connection.
Sometimes we fail to discover the PID of the process, or the path of the PID, thus in these cases if you check this option, a pop-up will be appear to allow or deny an "unknown connection".
**What's the behaviour of daemon's default action "deny"**
The daemon option "default_action" "deny" will block ALL traffic (as of version 1.0.0rc10) that is intercepted by _iptables_ and is not answered or configured by the user. If an outgoing connection timeouts while waiting for user action, then it'll apply the default action.
But not only that, because as we don't intercept ICMP, IGMP or SCTP (among others), they'll also be blocked. We'll add an option to configure this behaviour in the near future.
If you need to allow this kind of traffic, you can add a rule directly to iptables/nftables:
`iptables -t mangle -I OUTPUT -p icmp -j ACCEPT`
**In which order does opensnitch check configured rules?**
~As of version 1.0.1, there's no order to check the rules, it's random per each connection.~
~See this issue for more information regarding this question: [#36](https://github.com/gustavo-iniguez-goya/opensnitch/issues/36)~
Since version 1.2.0, rules checked in alphabetical order. There's a new field to mark a rule as Important.
So if you want to prioritize some rules over others:
1. Name the rule as 000-max-priority, 001-notsomax-priority, 002-less-preiority, not-priority
2. [x] Priority field checked (Action: allow)
3. OR Action: deny (not need to check the Priority field in these rules)

49
wiki/Getting-started.md Normal file
View file

@ -0,0 +1,49 @@
After installing opensnitch, the daemon will start intercepting connections and by default it'll allow them.
![](https://user-images.githubusercontent.com/2742953/85336535-0acaf000-b4df-11ea-9d69-c7bd7b597886.png)
When you open the GUI, you'll see all the connections and processes that has intercepted, and it'll prompt you to allow or deny new outgoing connections.
![](https://user-images.githubusercontent.com/2742953/85336893-bf651180-b4df-11ea-908e-6202e989a8ae.png)
The default action is to allow outgoing connections, so you can let it run for a while (hours, days, weeks), and observe what your machine is doing.
![](https://user-images.githubusercontent.com/2742953/85336695-55e50300-b4df-11ea-86d5-b70b78fd7896.png)
Once you know which are the common processes, IPs and hosts that your machine is connecting to, you can start creating rules to deny or allow them.
A common practice is to apply a rule of "Least privilege", i.e., block all by default and allow only those processes or connections that you want to.
[Read more about rules.](Rules)
![](https://user-images.githubusercontent.com/2742953/85337403-b294ed80-b4e0-11ea-8c65-d8251c6af25b.png)
![](https://user-images.githubusercontent.com/2742953/85337070-136ff600-b4e0-11ea-838a-439366c70668.png)
Some processes are part of the GNU/Linux ecosystem, and critical to the well functioning of it. Some of these processes are:
```
/usr/bin/xbrlapi
/usr/bin/dirmngr
/usr/bin/kdeinit5
```
Some others are not critical, but as part of the system they have their function, like discovering devices or resolving domains. For example:
```
/usr/libexec/colord-sane
/usr/sbin/avahi-daemon
/usr/libexec/dleyna-server-service
/lib/systemd/systemd-timesyncd
/usr/lib/systemd/systemd-resolved
```
Some applications launch external processes, so for example, you may be prompted to allow application A, and just right away asked to allow application B.
This is the case with Epiphany web browser, gnome-maps or snap: https://github.com/gustavo-iniguez-goya/opensnitch/issues/134#issuecomment-772876103
```
/usr/bin/epiphany
/usr/lib/x86_64-linux-gnu/webkit2gtk-4.0/WebKitNetworkProcess
```

21
wiki/Home.md Normal file
View file

@ -0,0 +1,21 @@
Welcome to the opensnitch wiki!
Download opensnitch from the [release](https://github.com/evilsocket/opensnitch/releases) section.
### Documentation
[How to install or compile from sources opensnitch](Installation).
[What can you configure and how it works.](Configurations)
[FAQs](FAQs)
[Known problems](Known-problems)
[Examples of opensnitch in action](OpenSnitch-in-action)
**HOWTOs**
[Complete guide to install and run opensnitch on RaspberryPI - by **Pain-Patate**](https://github.com/gustavo-iniguez-goya/opensnitch/issues/42)

89
wiki/Installation.md Normal file
View file

@ -0,0 +1,89 @@
### Installation using the packages
**tl;dr: use the command line**
#### DEB
> $ sudo dpkg -i opensnitch*.deb python3-opensnitch-ui*.deb; sudo apt -f install
#### RPM
> $ sudo yum localinstall opensnitch-1*.rpm; sudo yum localinstall opensnitch-ui*.rpm
**Note:**
This packages are provided to you in the aim of being useful and ease the installation. They have some no-no's (like calling pip on post install scripts), and apart from that don't expect them to be bug free or lintian errors/warnings free.
***
**Errors?**
- LinuxMint >= 18: see: [#16](https://github.com/gustavo-iniguez-goya/opensnitch/issues/16) or `apt-get install g++ python3-dev python3-wheel python3-slugify`
- MXLinux >= 19.x: You need to install additional packages: `apt-get install python3-dev python3-wheel`
- Pop!_ OS: if you find that opensnitch is not behaving correctly (it slowdowns your system for some reason), reinstall it using the one-liner above from the command line. It seems that there're troubles installing it using the graphical installer `eddy`.
- Fedora >= 3x: You can install `python3-grpcio` instead of the pip package.
- Ubuntu 16.04.x: Do not install the dependencies when the installer ask you to do so. After installing the package execute: `sudo pip3 install grpcio==1.16.1 protobuf`
---
The reason for installing some dependencies using `pip` is that they are not always packaged in all distributions and all versions (`python3-grpcio` on Ubuntu is only available from >= 19.x). Moreover, Ubuntu 20.04 `python3-grpcio` (version 1.16.1) differs from official 1.16.x that causes some working problems.
**Besides, grpc packages distributed with some distributions (python3-grpcio, OpenSuse) do not work.**
If you still don't want to install those pip packages, you'll need to install the following packages:
```
$ sudo apt install python3-grpcio python3-protobuf python3-slugify
```
* On Ubuntu you may need to add _universe_ repositories.
* If you install them using a graphical installer and fails, launch a terminal and type the above commands. See the [common errors](https://github.com/gustavo-iniguez-goya/opensnitch/wiki/Known-problems) for more information.
You can download them from the [release](https://github.com/gustavo-iniguez-goya/opensnitch/releases) section.
**Note:**
Select the right package for your architecture: `$(uname -m) == x86_64` -> opensnitch*...**amd64**.deb, `$(uname -m) == armhf` -> opensnitch*...**arhmf**.deb, etc.
***
**These packages have been (briefly) tested on:**
* Daemon (v1.0.0-rc5):
- RedHat Enterprise >= 7.0
- CentOS 8.x
- Fedora >= 24
- Debian >= 8
- LinuxMint >= 18
- Ubuntu >= 16 (works also on 14.04, but it lacks upstart service file. **dpkg must be at least .1.17.x**)
- OpenSuse
- Pop!_OS
- MX Linux 19.x
* UI (v1.0.0-rc4):
- Debian >= 9
- Ubuntu >= 16.x
- Fedora 3x
- OpenSuse Tumbleweed
- LinuxMint >= 18
- MX Linux
- Pop!_OS
* Window Managers:
- Cinnamon
- KDE
- Gnome-Shell (no systray icon? [see this for information](Known-problems#OpenSnitch-icon-does-not-show-up-on-gnome-shell))
- Xfce
- i3
Note: You can install the UI from the sources, using pip3, and it'll work in some more distributions. Not in Fedora <= 29 due to lack of PyQt5 libraries.
***
### Uninstalling opensnitch
**deb packages:**
- `apt remove opensnitch python3-opensnitch-ui`
* remove `/etc/opensnitchd/` after that: `rm -rf /etc/opensnitchd/`
**UI**
- `yum remove opensnitch opensnitch-ui` or `zypper remove opensnitch opensnitch-ui`
- `pip3 uninstall grpcio-tools unicode_slugify pyinotify`

162
wiki/Known-problems.md Normal file
View file

@ -0,0 +1,162 @@
[GUI crash/exception/does not show up](#GUI-crash-exception-or-does-not-show-up):
* NameError: name 'unicode' is not defined
* ModuleNotFoundError: No module named 'grpc'
* Others...
[no icons on the GUI](#no-icons-on-the-GUI)
[GUI size problems on 4k monitors](#GUI-size-problems-on-4k-monitors)
[OpenSnitch icon doesn't show up on Gnome-Shell](#OpenSnitch-icon-does-not-show-up-on-gnome-shell)
[opensnitchd/daemon does not start](#opensnitchd-does-not-start):
* `Error while creating queue #0: Error binding to queue: operation not permitted.`
* `Error while enabling probe descriptor for opensnitch_exec_probe: write /sys/kernel/debug/tracing/kprobe_events: no such file or directory`
* `Error while creating queue #0: Error binding to queue: operation not permitted.`
* `Error opening Queue handle: protocol not supported`
* `Could not open socket to kernel: Address family not supported by protocol (IPv6)`
* `Error while creating queue #0: Error unbinding existing q handler from AF_INET protocol` see [#323](https://github.com/evilsocket/opensnitch/issues/323). Issue not solved, if you can provide more information open a new issue please.
[Kernel panic on >= 5.6.16 || kernel hardening incompatibilities](#kernel-panics)
***
### GUI crash/exception or does not show up
If you have installed it by double clicking on the pkgs, using a graphical installer, try to install it from command line:
> $ sudo dpkg -i `*opensnitch*deb`; sudo apt -f install
See [issue #25](https://github.com/gustavo-iniguez-goya/opensnitch/issues/25), [issue #16](https://github.com/gustavo-iniguez-goya/opensnitch/issues/16) and [issue #32](https://github.com/gustavo-iniguez-goya/opensnitch/issues/32) for additional information.
--
You have to install `unicode_slugify` and `grpcio-tools`, usually not available in many distros. You can install them using pip:
```
pip3 install unicode_slugify
pip3 install grpcio-tools
```
--
Check that you don't have a previous installation of opensnitch GUI in _/usr/lib/python3*/*/opensnitch/_ or _/usr/local/lib/python3*/*/opensnitch/_
If you have a previous installation remove it, and install the GUI again (you may have an installation of the original repo).
If it doesn't work, report it describing the steps to reproduce it, and the exception or log. For example:
```
Traceback (most recent call last):
File "/usr/lib/python3.8/site-packages/opensnitch/dialogs/prompt.py", line 362, in _on_apply_clicked
self._rule.name = slugify("%s %s %s" % (self._rule.action, self._rule.operator.type, self._rule.operator.data))
File "/usr/lib/python3.8/site-packages/slugify.py", line 24, in slugify
unicode(
NameError: name 'unicode' is not defined
```
--
For ArchLinux/Manjaro users this worked:
> installed was from AUR python-unicode-slugify-git r43.b696c37-1
> removed it and installed python-unicode-slugify 0.1.3-1.
--
### No icons on the GUI
Be sure that you have properly set the icon theme of your Window Manager. [More information](https://github.com/gustavo-iniguez-goya/opensnitch/issues/53#issuecomment-671419790)
### GUI size problems on 4k monitors
Some users have reported issues displaying the GUI on 4k monitors. See [#43](https://github.com/gustavo-iniguez-goya/opensnitch/issues/43) for more information.
Setting these variables may help:
```
export QT_AUTO_SCREEN_SCALE_FACTOR=0
export QT_SCREEN_SCALE_FACTORS=1 (or 1.25, 1.5, 2, ...)
```
In case of multiple displays:
`export "QT_SCREEN_SCALE_FACTORS=1;1"`
--
### OpenSnitch icon does not show up on Gnome-Shell
On Gnome-Shell >= 3.16, systray icons have been removed. You have to install the extension [gnome-shell-extension-appindicator](https://extensions.gnome.org/extension/615/appindicator-support/) to get them back.
1. Download latest version - https://github.com/ubuntu/gnome-shell-extension-appindicator/releases
2. Install it with your regular user: `gnome-extensions install gnome-shell-extension-appindicator-v33.zip`
See this comment/issue for more information: [#44](https://github.com/gustavo-iniguez-goya/opensnitch/issues/44#issuecomment-654373737)
--
### opensnitchd does not start
A common error you may encounter (in the original repo):
> [2019-08-08 11:51:14] !!! Error while enabling probe descriptor for opensnitch_exec_probe: write /sys/kernel/debug/tracing/kprobe_events: no such file or directory
This is because opensnitch uses [ftrace](https://www.kernel.org/doc/Documentation/trace/ftrace.txt) to get running processes (PIDs).
`ftrace` mounts a file system called _debugfs_ in /sys/kernel/debugfs, and outputs kernel events to _/sys/kernel/debugfs/tracing/trace_ and _/sys/kernel/debugfs/tracing/trace_pipe_
If for some reason those files can not be opened, opensnitch will not work.
Some reasons because `ftrace` is not available:
* debugfs is not mounted. If it's mounted you should see a similar output:
```
$ mount | grep debugfs
none on /sys/kernel/debug type debugfs (rw)
$
```
* log in syslog or journalctl: _Lockdown: opensnitchd: Use of kprobes is restricted; see man kernel_lockdown.7_
Quoting `anreiple` in issue [#235](https://github.com/evilsocket/opensnitch/issues/235):
> Since kernel 4.17 if you have UEFI Secure Boot enabled then kernel does lockdown - using kernel probes, 3rd party kernel modules (even signed), etc is restricted
Starting from version [v1.0.0-rc3](https://github.com/gustavo-iniguez-goya/opensnitch/releases/tag/v1.0.0-rc3), there's an alternative method to workaround this problem.
---
**Error while creating queue #0: Error binding to queue: operation not permitted**
> [2020-06-13 17:07:34] !!! Error while creating queue #0: Error binding to queue: operation not permitted.
Fixed in 1.0.0rc10. If you still see this error open a new issue and [provide the following information](https://github.com/gustavo-iniguez-goya/opensnitch/issues/18#issuecomment-643661484)
***
**Address family not supported**
[See this issue for more information](https://github.com/gustavo-iniguez-goya/opensnitch/issues/52)
***
**Error opening Queue handle: protocol not supported**
> [2020-10-09 19:11:15] !!! Error while creating queue #0: Error opening Queue handle: protocol not supported
Check that you have the needed iptables modules loaded: nfnetlink, nfnetlink_queue and x_tables.
`# lsmod | grep nfnetlink`
See this issue [#71](https://github.com/gustavo-iniguez-goya/opensnitch/issues/71) for more information.
***
### Kernel panics
Some users have reported kernel panics with kernel 5.6.16 ([#297](https://github.com/evilsocket/opensnitch/issues/297)) and other kernels([#41](https://github.com/gustavo-iniguez-goya/opensnitch/issues/41)). **deathtrip** found that the culprit in his/her case was a configuration of the Arch's [linux-hardened](https://www.archlinux.org/packages/extra/x86_64/linux-hardened/) kernel command line option.
Removing the following options from the kernel booting parameters solved the issue:
`slab_nomerge, slub_debug=FZP and page_alloc.shuffle=1`
On Debian with kernel 5.7.0, remove `slub_debug=FZP` if you have it configured and try again.
**Note:** This was caused by [a bug in the libnetfilter_queue library](https://bugzilla.netfilter.org/show_bug.cgi?id=1440).

8
wiki/OpenSnitch-in-action.md Normal file
View file

@ -0,0 +1,8 @@
List of real world examples of opensnitch in action (if you want to share an experience we'd love to hear it! open a new issue and describe it).
- [a chrome extension that sends your data (facebook, location, etc) to their servers](https://github.com/gustavo-iniguez-goya/opensnitch/issues/21)
- [A website port scanning your PC](https://user-images.githubusercontent.com/2742953/84960681-9a992480-b102-11ea-9f03-e0ac1bd5449d.png). Context: [0](https://www.bleepingcomputer.com/news/security/list-of-well-known-web-sites-that-port-scan-their-visitors/), [1](https://nullsweep.com/why-is-this-website-port-scanning-me/)
- [a deb package downloading data from internet](https://user-images.githubusercontent.com/2742953/85128093-e944dc80-b230-11ea-908d-b360ba93151f.png)
- Note: In this case it's the expected behavior, but it's good to know these things.
- [Firefox sending a crash report, even having it configured to not do it.](https://user-images.githubusercontent.com/2742953/100526334-1de99680-31c8-11eb-904e-06a6e2de2377.png)

7
wiki/Process-monitor-dialog.md Normal file
View file

@ -0,0 +1,7 @@
Since version v1.3.0-rc.1 you can monitor more aspects of a process, not only connections.
To access this dialog, go to Processes tab and click on the icon next to the process name:
![](https://user-images.githubusercontent.com/2742953/99863019-83240300-2b9c-11eb-968e-f773f88c99f6.png)
![](https://user-images.githubusercontent.com/2742953/99863173-3987e800-2b9d-11eb-93f2-fe3121b18c51.png)

117
wiki/Rules-editor.md Normal file
View file

@ -0,0 +1,117 @@
Rules can be edited from the GUI, by clicking on the name of the rule:
![image](https://user-images.githubusercontent.com/2742953/82753008-95c2a880-9dc2-11ea-8c6a-23e1ce0f3aa4.png)
![image](https://user-images.githubusercontent.com/2742953/98868147-f8425a80-246f-11eb-99b4-5d441b5d5b95.png)
(Since v1.2.0, all rules comparison are case-insensitive by the default for destination host, process path and process arguments.)
#### Parameters
[x] Enable - Enables or disables the rule.
[x] Priority - Indicates that this rule has precedence over the rest.
[x] Case sensitive - Make the comparison case-sensitive for ALL fields.
[x] Duration - Always writes the rule to disk.
---
Each field can be literal or a regex expression.
Some examples:
- Filtering by multiple ports:
`[x] To this port: ^(53|80|443)$`
targets ports 53 OR 80 OR 443.
`[x] To this port: ^555[12345]$`
targets ports 5551, 5552, 5553, 5554 OR 5555.
- Filtering by an exact domain, and nothing else: `[x] To this host: github.com` (will match only github.com, not www.github.com, etc)
- Filtering by a domain and its subdomains: `[x] To this host: .*\.github.com`
- Filtering an executable path:
`[x] From this executable: /usr/bin/python3`
(warning: /usr/bin/python3.6/3.7/3.8/etc won't match this rule)
- Allow common system commands:
```
Name: 000-allow-system-cmds
Action: Allow
[x] Priority rule
[x] From this executable: ^(/usr/sbin/ntpd|/lib/systemd/systemd-timesyncd|/usr/bin/xbrlapi|/usr/bin/dirmngr)$
[x] To this port: ^(53|123)$
[x] From this User ID: ^(0|115|118)$
```
- Blocking connections made by executables launched from /tmp:
```
Action: Deny
[x] From this executable: /tmp/.*
```
- Filtering an executable path with regexp, for example any python binary in /usr/bin/:
`[x] From this executable: ^/usr/bin/python[0-9\.]*$`
Case insensitive rules:
`[x] From this executable: (?i:.*ping)`
![](https://user-images.githubusercontent.com/2742953/85209253-aa994a00-b336-11ea-87d9-a7a650510b6b.png)
- Filtering LAN IPs or multiple ranges:
^(127\..*|172\..*|192.168\..*|10\..*)$
See these issues for some discussions and more examples: [#17](https://github.com/gustavo-iniguez-goya/opensnitch/issues/17), [#31](https://github.com/gustavo-iniguez-goya/opensnitch/issues/31), [#73](https://github.com/gustavo-iniguez-goya/opensnitch/issues/73)
**Note:** Don't use "," to specify domains, IPs, etc. It's not supported. For example this won't work (it could be added if you complain loud enough):
> [x] To this host: www.example.org, www.test.me
---
[Python regular expression documentation](https://docs.python.org/3.3/howto/regex.html)
[Golang regular expression documentation](https://golang.org/pkg/regexp/syntax/)
[Golang regular expression syntax](https://github.com/google/re2/wiki/Syntax)
**Note:** Golang does not support Perl syntax (like (?!...))
However you can use negated chars classes. For example, block all outgoing connections, except those to localhost:
`[x] Action: deny`
`[x] To this destination IP: [^:127.0.0.1:]`
***
**Unconditionally blocking lists**
As of v1.0.0rc10 there's no support for blocking or allowing connections ignoring the rest of the rules (see [#36](https://github.com/gustavo-iniguez-goya/opensnitch/issues/36)).
But you can achieve it using iptables:
- Allow ICMP:
`iptables -t mangle -I OUTPUT -p icmp -j ACCEPT`
- Allow localhost connections:
`iptables -t mangle -I OUTPUT -d 127.0.0.1 -j ACCEPT`
Note on allowing all connections to localhost:
While it might be seem obvious to allow everything to localhost, be aware that you might want to allow only certain connections/programs:
[OpenSnitch in action](OpenSnitch-in-action)
---

155
wiki/Rules.md Normal file
View file

@ -0,0 +1,155 @@
### Rules format
Rules are stored as JSON files inside the `-rule-path` folder, in the simplest case a rule looks like this:
```json
{
"created": "2018-04-07T14:13:27.903996051+02:00",
"updated": "2018-04-07T14:13:27.904060088+02:00",
"name": "deny-simple-www-google-analytics-l-google-com",
"enabled": true,
"precedence": false,
"action": "deny",
"duration": "always",
"operator": {
"type": "simple",
"sensitive": false,
"operand": "dest.host",
"data": "www-google-analytics.l.google.com"
}
}
```
| Field | Description |
| -----------------|---------------|
| created | UTC date and time of creation. |
| update | UTC date and time of the last update. |
| name | The name of the rule. |
| enabled | Use to temporarily disable and enable rules without moving their files. |
| precedence | true or false. Sets if a rule take precedence (>= v1.2.0)|
| action | Can be `deny` or `allow`. |
| duration | For rules persisting on disk, this value is default to `always`. |
| operator.type | Can be `simple`, in which case a simple `==` comparison will be performed, or `regexp` if the `data` field is a regular expression to match. |
| operator.operand | What element of the connection to compare, can be one of: |
| |* `true` (will always match) |
| |* `process.path` (the path of the executable) |
| |*`process.id` PID|
| |*`process.command` (full command line, including path and arguments)|
| |*`provess.env.ENV_VAR_NAME` (use the value of an environment variable of the process given its name)
| |*`user.id` (UID)|
| |*`protocol`|
| |*`dest.ip` |
| |*`dest.host` |
| |*`dest.network` (>= v1.3.0)|
| |* `dest.port`. |
| operator.data | The data to compare the `operand` to, can be a regular expression if `type` is `regexp`. |
### Some considerations
By default Deny rules take precedence over the rest of the rules. If a connection match a Deny rule, opensnitch won't continue evaluating rules.
Since v1.2.0, rules are sorted and checked in alphabetical order. You can name them this way to prioritize Deny rules, for example:
```
000-allow-very-important-rule
001-allow-not-so-important-rule
001-deny-xxx
```
Also since v1.2.0, you can configure a rule as _Important_ ([x] Priority) to take precedence over the rest of the rules. If you set this flag and name the rule as mentoned above, you can also prioritize Allow rules.
This way you can not only prioritize critical connections (like VPNs), but also gain performance.
**More on rules performance**
As already mentioned, the order of the rule is critical. If you prioritize Firefox the web navegation will be faster.
But the type of rule also impacts the rules performance. `regexp` and `list` types are slower than `simple`, in the end, `regexp` and `list` types check multiple parameters while simple rules check just one.
---
An example with a regular expression:
```json
{
"created": "2018-04-07T14:13:27.903996051+02:00",
"updated": "2018-04-07T14:13:27.904060088+02:00",
"name": "deny-any-google-analytics",
"enabled": true,
"precedence": false,
"action": "deny",
"duration": "always",
"operator": {
"type": "regexp",
"sensitive": false,
"operand": "dest.host",
"data": "(?i)
}
}
```
An example whitelisting a process path:
```json
{
"created": "2018-04-07T15:00:48.156737519+02:00",
"updated": "2018-04-07T15:00:48.156772601+02:00",
"name": "allow-simple-opt-google-chrome-chrome",
"enabled": true,
"precedence": false,
"action": "allow",
"duration": "always",
"operator": {
"type": "simple",
"sensitive": false,
"operand": "process.path",
"data": "/opt/google/chrome/chrome"
}
}
```
Example of a complex rule using the operator _list_, saved from the GUI (Note: version v1.2.0):
```
{
"created": "2020-02-07T14:16:20.550255152+01:00",
"updated": "2020-02-07T14:16:20.729849966+01:00",
"name": "deny-list-type-simple-operand-destip-data-1101-type-simple-operand-destport-data-23-type-simple-operand-userid-data-1000-type-simple-operand-processpath-data-usrbintelnetnetkit",
"enabled": true,
"precedence": false,
"action": "deny",
"duration": "always",
"operator": {
"type": "list",
"operand": "list",
"data": "[{\"type\": \"simple\", \"operand\": \"dest.ip\", \"data\": \"1.1.0.1\"}, {\"type\": \"simple\", \"operand\": \"dest.port\", \"data\": \"23\"}, {\"type\": \"simple\", \"operand\": \"user.id\", \"data\": \"1000\"}, {\"type\": \"simple\", \"operand\": \"process.path\", \"data\": \"/usr/bin/telnet.netkit\"}]",
"list": [
{
"type": "simple",
"operand": "dest.ip",
"sensitive": false,
"data": "1.1.0.1",
"list": null
},
{
"type": "simple",
"operand": "dest.port",
"sensitive": false,
"data": "23",
"list": null
},
{
"type": "simple",
"operand": "user.id",
"sensitive": false,
"data": "1000",
"list": null
},
{
"type": "simple",
"operand": "process.path",
"sensitive": false,
"data": "/usr/bin/telnet.netkit",
"list": null
}
]
}
}
```

94
wiki/System-rules.md Normal file
View file

@ -0,0 +1,94 @@
Since v1.3.0-rc.1 you can configure `iptables` rules by editing the file `/etc/opensnitchd/system-fw.json`.
OpenSnitch will ensure that the rules you have configured there are not deleted from the system.
#### Allowing VPN traffic and other things
If you configure the daemon to deny everything that is not specifically allowed by default, many services will be blocked, [like VPNs](https://github.com/gustavo-iniguez-goya/opensnitch/issues/47).
In order to allow this type of traffic, you can add a rule like this (notice that the **Table** is **mangle**):
```
{
"SystemRules": [
{
"Rule": {
"Description": "Allow pptp VPNs",
"Table": "mangle",
"Chain": "OUTPUT",
"Parameters": "-p gre",
"Target": "ACCEPT",
"TargetParameters": ""
}
}
]
}
```
In this case we allow **GRE traffic** (`-p gre`) to allow **PPTP** connections, or you can allow traffic point to point (`-p udp --dport 1194`). Whatever you can do with iptables.
Besides this, some services like **OpenVPN** uses **ICMP** to keep the tunnel up. Needless to say that [ICMP is very important for network communications](https://tools.ietf.org/html/rfc1191):
```
{
"SystemRules": [
{
"Rule": {
"Description": "Allow OUTPUT ICMP",
"Table": "mangle",
"Chain": "OUTPUT",
"Parameters": "-p icmp",
"Target": "ACCEPT",
"TargetParameters": ""
}
}
]
}
```
(you can allow only _echo_ and `reply`: `-p icmp --icmp-type echo-request`)
Some more examples:
```
{
"SystemRules": [
{
"Rule": {
"Description": "",
"Table": "mangle",
"Chain": "OUTPUT",
"Parameters": "-p tcp ! --syn -m conntrack --ctstate NEW",
"Target": "DROP",
"TargetParameters": ""
}
},
{
"Rule": {
"Description": "",
"Table": "filter",
"Chain": "OUTPUT",
"Parameters": "-m conntrack --ctstate UNTRACKED,INVALID",
"Target": "DROP",
"TargetParameters": ""
}
},
{
"Rule": {
"Description": "",
"Table": "mangle",
"Chain": "PREROUTING",
"Parameters": "-m conntrack --ctstate INVALID,UNTRACKED",
"Target": "DROP",
"TargetParameters": ""
}
}
]
}
```
The list of protocols you can allow or deny are in the file `/etc/protocols`
In future versions you will be able to configure these rules from the GUI, but for now you have to add the rules to this file.
If you need or want a GUI, or you'd like to have more control on the rules, maybe you should try UFW, FwBuilder and the like.

289
wiki/Why-OpenSnitch-does-not-intercept-application-XXX.md Normal file
View file

@ -0,0 +1,289 @@
**tl;dr**
- because we don't use eBPF.
- a process is opening connections too fast (nmap for example, firefox sometimes...).
- the system has a high load and we're unable to find the process in time.
- _netlink_ does not return the connection we're querying for, thus we can't search for the PID.
- the connection does not exist in `/proc/net/tcp|udp|udplite|`...
- the Inode does not exist under `/proc/<PID>/fd/`
- the PID entry does not exist under `/proc/`
Some discussions you may want to read: [#10](https://github.com/gustavo-iniguez-goya/opensnitch/issues/10#issuecomment-608428026) and [#84](https://github.com/gustavo-iniguez-goya/opensnitch/issues/84#issuecomment-721663451)
***
In order to know what process opened a particular connection (in userspace), we need to perform at least 4 steps:
1. Intercept the connection using iptables and redirect it to us.
2. Find the socket inode of the connection (SockFS):
2.1 Using ProcFS
2.2 or using netlink
3. Find the PID of the connection:
3.1 Using auditd
3.2 or using Ftrace (kprobes)
3.3 or using ProcFS
4. Find the application name and the command line (and (optionally) the directory from where it was executed):
4.1 Using auditd
4.2 Using ProcFS
#
### 1. Intercept the connection using iptables and redirect it to us.
When a new connection is opened, 5 steps happen in the system (well, [many more](https://makelinux.github.io/kernel/map/), but for simplicity sake):
1. An application creates a socket() [[0]](#0---how-linux-creates-sockets).
2. A socket Inode is allocated [[1]](#1---Demystifying-the-Linux-Kernel-Socket-File-Systems).
3. The connection details are dumped to `ProcFS` [kernel procfs documentation](https://www.kernel.org/doc/html/latest/filesystems/proc.html?highlight=proc) [man](https://www.tldp.org/LDP/Linux-Filesystem-Hierarchy/html/proc.html).
4. The connection travels through iptables [[2]](#2---the-netfilter-framework).
5. The connection leaves the system.
When it is about to leave the system, we don't know the socket Inode nor the PID of the process who created it, thus we can't show the name of the process who created the connection to the user. What we only know is the connection details: source port/IP and destination port/IP (and usually the UID of the user who opened it).
That's why we need to find the PID using different mechanisms (asking the kernel via [netlink](#5---netlink-howto), parsing /proc, eBPF...).
We know that the path a new connection follows when it's created by a local process is as follow:
socket() -> ::route decision:: -> <IPTABLES> (RAW chain)OUTPUT -> [conntrack module] -> (MANGLE chain)OUTPUT -> ::reroute if needed:: -> (NAT table)OUTPUT -> (FILTER table)OUTPUT -> (* table)POSTROUTING <IPTABLES>
![](https://i.stack.imgur.com/YkwUi.png)
If we use a [netfilter queue](https://home.regit.org/netfilter-en/using-nfqueue-and-libnetfilter_queue/), then we can redirect every connection to a queue:
> iptables -t mangle -I OUTPUT -m conntrack --ctstate NEW -j NFQUEUE --queue-num 0 --queue-bypass
If we launch a process that listens on that queue, we can get the details of every NEW connection that is opened.
So, we know that a connection is about to leave the system, and now we have the source port/ip and destination/port, how do we find out the PID of the process?
**Notes:**
> In this case we only redirect NEW connections in the _mangle_ table. That means that we can access and use the information of connections statuses provided by the conntrack kernel module. [[1]](#1---Demystifying-the-Linux-Kernel-Socket-File-Systems).
>
> nanoseconds prior to this point, a socket has been created by a local process, but it may be too late to get the socket Inode (if it's written to `/proc` at all) or the application can bypass that rule by crafting a special packet with an invalid state.
>
> One thing you can play with is, to add a rule to intercept connections in the RAW table:
> > iptables -t raw -I OUTPUT -j NFQUEUE --queue-num 0 --queue-bypass
>
> Notice that at this point of the path, we can't know if a connection is NEW, ESTABLISHED or INVALID, so every packet is forwarded to opensnitch. That means that the performance may be degraded, using too much CPU.
>
> But on the other hand, we're intercepting connections faster and earlier than on the MANGLE table, so maybe we can get processes faster and not miss them.
>
> You can also add the following rule (notice that we exclude ESTABLISHED state):
> > iptables -t mangle -I OUTPUT -m conntrack --ctstate NEW,RELATED,INVALID,SNAT,DNAT -j NFQUEUE --queue-num 0 --queue-bypass
#
### 2. Find the socket Inode of the connection (sockfs)
In order to identify a connection we need an Inode. Basically because there's no way to get the PID directly (without using eBPF). If you realize, we're going backwards, undoing what the kernel did (sys_socket() -> sock_create() -> sock_alloc() -> sock_alloc_inode() -> <iptables>).
What we know at this point?
Socket Inodes are written to `/proc/<PID>/fd/` (and `/proc/<PID>/task/<TID>/fd/`). The files written there are symlinks (not exactly, but neverminds now), and point to the type of object it points to, for example:
```
$ ls -l /proc/1/fd/
lrwx------. 1 root root 64 mar 8 16:37 99 -> 'socket:[18403475]'
lrwx------. 1 root root 64 mar 8 16:37 99 -> 'anon_inode:[eventpoll]'
lrwx------. 1 root root 64 mar 8 16:37 99 -> 'anon_inode:[timerfd]'
```
As we see, the first link is a socket, and the number is the inode. We can search `/proc/net/` to try to know to what connection is linked to:
```
$ grep 18403475 /proc/net/*
/proc/net/unix:ffff9a16790e1800: 00000003 00000000 00000000 0001 03 18403475 /run/systemd/journal/stdout
```
In this case, it's a UNIX socket, and the connection in this case is a Path to a file in the filesystem (`/run/systemd/journal/stdout`)
So knowing that we can parse `/proc/net` for connections and inodes, when a new connection is redirected to our process, we can search for it in `/proc/net/` because we know the source port, source IP, destination port and destination IP.
```
$ cat /proc/net/tcp
sl local_address rem_address st tx_queue rx_queue tr tm->when retrnsmt uid timeout inode
0: 0100007F:13AD 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 18083222 1 ffff9a1677a8cec0 100 0 0 10 0
```
Parsing `/proc` is easy and very straightforward. But it has its caveats, specially with UDP connections. In many occasions, when you parse `/proc/net/udp` the connection is already gone. Not to mention, that hiding connections from ProcFS is a common practice by malware.
So, what can we do? We can use `netlink` and `sock_diag`.
What is netlink? from [man 7 netlink](http://man7.org/linux/man-pages/man7/netlink.7.html):
> Netlink is used to transfer information between the kernel and user-space processes.
What is sock_diag? from [man sock_diag](http://man7.org/linux/man-pages/man7/sock_diag.7.html):
> The sock_diag netlink subsystem provides a mechanism for obtaining
> information about sockets of various address families from the
> kernel. This subsystem can be used to obtain information about
> individual sockets or request a list of sockets.
> In the request, the caller can specify additional information it
> would like to obtain about the socket, for example, memory
> information or information specific to the address family.
When we ask the kernel for a specific socket, it responds with a struct with the following fields:
```
struct inet_diag_msg {
__u8 idiag_family;
__u8 idiag_state;
__u8 idiag_timer;
__u8 idiag_retrans;
struct inet_diag_sockid id;
__u32 idiag_expires;
__u32 idiag_rqueue;
__u32 idiag_wqueue;
__u32 idiag_uid;
__u32 idiag_inode; <---
};
```
So there it is, the inode. How do we query netlink for a particular connection? We can use the following struct with the details of the connection:
```
struct inet_diag_sockid {
__be16 idiag_sport;
__be16 idiag_dport;
__be32 idiag_src[4];
__be32 idiag_dst[4];
__u32 idiag_if;
__u32 idiag_cookie[2];
};
```
The query is something like "ok netlink, give me the Inode of the connection net_diag_sockid{ diag_sport = 45678; diag_dport = 53; idiag_dst="1.1.1.1" }", and netlink will response with that connection details.
However netlink does not always return a match (TODO: explain why), specially for UDP/broadcast connections.
In these cases we can query just for the source port of the connection, which normally will return just one entry, and in some cases (ntp) it will return several inodes for the same srcPort:srcIP<->dstIP:dstPort connection.
#
### 3. Find the PID of the connection
Once we find the Inode, the next thing is to search for it under `/proc`, looking for it under every PID directory. pseudocode:
```
for pid in $(ls /proc)
do
ls -l /proc/$pid/fd/ | grep 27449873
if [ $? -eq 0 ]; then
echo "found: $(cat /proc/$pid/cmdline)"
break
fi
done
```
```
lrwx------. 1 ga ga 64 mar 8 16:32 109 -> socket:[27449873]
found: /usr/bin/iceweasel
```
easy, right? It is. However, when we reach to this point, the process may have already exited, or the socket being closed. It's not accurate, and besides, many rootkits hide their activity from `/proc` (PIDs, connections, etc).
What options do we have then?
One approach is to have a list of known PIDs, this is, a list of PIDs which have opened connections.
We listen asynchronously for PIDs which open sockets, and when a connection hits the NFQUEUE target and it's redirected to our process, we can get the Inode and search for the PID in a very small list of PIDs. That increase the chances to get the correct PID/process name.
> Another trick is by sorting /proc entries by modified time. Processes that opened a socket will be at the top.
We can also accomplish it using different methods:
#### auditd
> auditd is the userspace component to the Linux Auditing System. It's responsible for writing audit records to the disk
[Linux Auditing System](https://github.com/linux-audit/audit-kernel):
> The Linux Audit subsystem provides a secure logging framework that is used to capture and record security relevant events. It consists of a kernel component which generates audit records based on system activity, a userspace daemon which logs these records to a local file or a remote aggregation server, and a set of userspace tools to for audit log inspection and post-processing.
We can add rules to auditd, to filter for sycalls, thus we can filter by socket/socketpair/connect/execve, etc:
> auditctl -a exit,always -F arch=b64 -S socket,connect,bind -k opensnitch
Now if you look in journalctl, you'll see a lot of auditd messages:
```
mar 08 18:37:48 ono-sendai audit[12704]: SYSCALL arch=c000003e syscall=41 success=yes exit=204 a0=a a1=2 a2=0 a3=7f02480008d0 items=0 ppid=12654 pid=12704 auid=1000 uid=1000 gid=1000 euid=1000 suid>
mar 08 18:37:48 ono-sendai audit: PROCTITLE proctitle="iceweasel"
mar 08 18:37:48 ono-sendai audit: PATH item=0 name="/run/user/1000/bus" inode=41813 dev=00:15 mode=0100400 ouid=0 ogid=0 rdev=00:00 obj=unconfined_u:object_r:var_run_t:s0 nametype=NORMAL cap_fp=0 c>
mar 08 18:37:48 ono-sendai audit: CWD cwd="/tmp"
mar 08 18:37:48 ono-sendai audit: SOCKADDR saddr=01002FF2756E2F7FF573613030302F343435627573
```
If you look close enough, you'll see that it's reporting the PID which opened the socket (pid=12704). And this is reported very fast, as soon as it happens.
Thus, we can go directly to `/proc/<PID>`, without having to iterate over all the `/proc` entries.
#### FTrace (kprobes)
Another method we can use is ftrace:
https://www.kernel.org/doc/html/latest/trace/ftrace.html
> Ftrace is an internal tracer designed to help out developers and designers of systems to find what is going on inside the kernel. It can be used for debugging or analyzing
Ftrace uses the `debugfs` file system, which is mounted at /sys/kernel/debug/. It's enabled by default, but some users disables it or some distributions do not enable it by default.
For brevity shake, I'll point you to the documentation to learn more about this world.
We can tell the kernel to log every new connection, socket, process, file, etc that is opened in the system as follow:
```
# cd /sys/kernel/debug/tracing/
# echo 'p:m security_socket_connect' > krpobe_events
# echo 1 > events/kprobes/m/enable
# cat trace_pipe
```
and the output:
```
Chrome_ChildIOT-14550 [000] .... 119979.685064: m: (security_socket_connect+0x0/0x50)
opensnitchd-3289 [006] .... 119980.096912: m: (security_socket_connect+0x0/0x50)
```
As you can see, as soon as a program opens a new connection (security_socket_connect), it's written to `trace_pipe` along with the PID and the common name of the process. We could also get the source port/IP and destination port/IP.
Using this method we don't have to lookup the inode of the connection, we'd just go directly to `/proc/<PID>/` to get the path of the process.
### ProcFS
***
**References:**
##### 0 - How Linux creates sockets
https://ops.tips/blog/how-linux-creates-sockets/
##### 1 - Demystifying the Linux Kernel Socket File Systems
http://www.voidcn.com/article/p-kxdmdjfh-zd.html
##### 2 - The netfilter framework
https://people.netfilter.org/pablo/docs/login.pdf
##### 3 - RAW sockets
https://sock-raw.org/papers/sock_raw
##### 4 - netlink howto
https://lwn.net/Articles/208755/
##### 5 - Linux kernel networking overview
https://linux-kernel-labs.github.io/refs/heads/master/labs/networking.html#
##### 7 - Simple UDP Server
https://kernelnewbies.org/Simple_UDP_Server
##### 8 - Disco Wall source code, an Android Firewall using NFQUEUE
https://github.com/T7o7heVV/DiscoWall
##### 9 - DiscoWall: Design And Implementation Of A Firewall For Android Phones
http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.705.2552&rep=rep1&type=pdf
##### 10 - A deep dive into iptables and netfilter architecture
https://www.digitalocean.com/community/tutorials/a-deep-dive-into-iptables-and-netfilter-architecture

19
wiki/_Sidebar.md Normal file
View file

@ -0,0 +1,19 @@
1. [Installation](Installation)
2. [Getting started](Getting-started)
1. Events window
2. [Process monitor dialog](Process-monitor-dialog)
3. [Configuration](Configurations)
1. [Monitor method: audit](monitor-method-auditd)
2. [Rules](Rules)
3. [Rules editor](Rules-editor)
4. [System rules](System-rules)
4. [Compilation](Compilation)
1. [Cross-compilation for arm](Cross-compilation)
2. [Building packages with pbuilder](Building-packages-with-pbuilder)
5. GUI translations
1. [Adding, updating and installing translations](Adding,-updating-and-installing-new-translations)
6. FAQs and common errors
1. [Known problems](Known-problems)
2. [FAQs](FAQs)
3. [Why OpenSnitch does not intercept application XXX](Why-OpenSnitch-does-not-intercept-application-XXX)
7. [Examples OpenSnitch in action](OpenSnitch-in-action)

39
wiki/monitor-method-auditd.md Normal file
View file

@ -0,0 +1,39 @@
In order to use auditd to get the name of a process which is opening a new connection, you have to install and configure it first.
On Debian/Ubuntu:
* apt install auditd audispd_plugins
* enable af_unix plugin `/etc/audisp/plugins.d/af_unix.conf` (active = yes)
* add a test rule: `auditctl -a always,exit -F arch=b64 -S socket,connect,execve -k test`
* increase `/etc/audisp/audispd.conf` q_depth if there're dropped events: q_depth = 4096)
* set `write_logs` to no if you don't need/want audit logs to be stored in the disk.
* read messages from the pipe to verify that it's working:
`socat unix-connect:/var/run/audispd_events stdio`
You'll see lot of messages like these ones:
```
mar 08 18:37:48 ono-sendai audit[12704]: SYSCALL arch=c000003e syscall=41 success=yes exit=204 a0=a a1=2 a2=0 a3=7f02480008d0 items=0 ppid=12654 pid=12704 auid=1000 uid=1000 gid=1000 euid=1000 suid>
mar 08 18:37:48 ono-sendai audit: PROCTITLE proctitle="iceweasel"
mar 08 18:37:48 ono-sendai audit: PATH item=0 name="/run/user/1000/bus" inode=41813 dev=00:15 mode=0100400 ouid=0 ogid=0 rdev=00:00 obj=unconfined_u:object_r:var_run_t:s0 nametype=NORMAL cap_fp=0 c>
mar 08 18:37:48 ono-sendai audit: CWD cwd="/tmp"
mar 08 18:37:48 ono-sendai audit: SOCKADDR saddr=01002FF2756E2F7FF573613030302F343435627573
```
**Possible errors:**
* `AuditReader: auditd error%!(EXTRA *net.OpError=read unix @->/var/run/audispd_events: use of closed network connection)`
You need to restart auditd (service auditd restart)
**More information on this system:**
Audit event fields:
https://github.com/linux-audit/audit-documentation/blob/master/specs/fields/field-dictionary.csv
Record types:
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/sec-Audit_Record_Types.html
Documentation:
https://github.com/linux-audit/audit-documentation