Documentation

Code of Conduct

SecBSD is inclusive. We want SecBSD to be a space where people of all backgrounds can collaborate to create the best offensive toolkit known to mankind, crafted by a strong and florishing community. Our core values extend beyond just the development, but encompass SecBSD as a whole.

Diversity is a huge strength and is critical to the long term success of SecBSD. To that end we have a few ground rules that we ask people to adhere to. This code applies equally to everyone representing the SecBSD project. in any way, from new members, to committers, to the core team itself. These rules are intended to ensure a safe, harassment-free environment for all and to ensure that everyone feels welcome both working within, and interacting with, the project.

This document is not an exhaustive list of things that you should not do. Rather, consider it a guide to make it easier to enrich all of us and the technical communities in which we participate. This code of conduct applies to all spaces used by the SecBSD project; online and offline.

Respect the opinion, attitude, background, preferences, traits and human aspects of others.

Do not discriminate others, based on any and all aspects - whether negative or positive.

SecBSD is about collaborating, the community and creating a toolkit. The project is not - in any way - a platform to harass others, including but not limited to unwanted attention, intimidation, stalking, trolling, sexual attention, etc.

Try to substantiate shared information and opinions rather than stating your opinion as-if it were a fact.

Contributing

SecBSD will base releases upon the -stable branch of OpenBSD.
If you are contributing code o ports devel runs on -current.

Requirements

A code editor of your liking (ed, vi, vim, emacs, etc)

A machine running SecBSD.

1. Install some dependencies

$ doas pkg_add git gnupg

GPG is used to signing commits, which is strongly preferred though not required (as of now).

2. (Optional) clone the repository that best fits your idea.

3. Either start with working out your idea (ports, code, docs) or message Purple Rain or h3artbl33d about to-do's

4. Submit your work through a pull request or by contacting a core member. We do require at least one core member signing off commits.

Things worth noting

We respect your privacy. It is up to you whether you want to disclose any personal details. If you want to be solely known by your nickname, you might want to create an identity dedicated to the SecBSD project (nickname, emailaddress and GPG key). Be sure to route your traffic over a pseudo-anonymous VPN network or via Tor.

While we require a core member signing your contributions, you and only you are responsible and remain responsible for your contributions. Eg, if you are contributing a port: keep it up to date with upstream. If not kept up-to-date, we might consider the port to be obsolete and eventually remove it.

Currently, we do not have an established means of communication, like IRC/XMPP or a forum. As soon as anything is setup, we'll update this document accordingly.

Overview of the Installation Procedure

The SecBSD installer uses a special ramdisk kernel (bsd.rd) that spawns a live environment running entirely in memory. It contains the install script and a small number of utilities needed to perform a complete installation. These utilities can also be useful for disaster recovery.

The ramdisk kernel can be booted from a number of different sources:

CD/DVD
USB drive
An existing partition
Over the network
(PXE or other network boot options)
Floppy disk
Not every platform supports all of these options.

If you have a running SecBSD system, bsd.rd is all you need to reinstall or upgrade to a newer version. To do so, download and verify the new bsd.rd, place it on an existing filesystem, and boot from it. The general method of booting bsd.rd is to change your boot kernel from /bsd to /bsd.rd through whatever means used on your platform.

Booting from bsd.rd on an amd64 system can be done like so:

Using drive 0, partition 3.
Loading......
probing: pc0 com0 com1 mem[638K 1918M a20=on]
disk: hd0+ hd1+
>> SecBSD/amd64 BOOT 3.33
boot> bsd.rd

This will boot the kernel named bsd.rd from the first partition of the first recognized hard disk.

If you need to specify a different drive or partition, just prefix the kernel name with its location. The following example would boot from the fourth partition of the second hard drive:

Using drive 0, partition 3.
Loading......
probing: pc0 com0 com1 mem[638K 1918M a20=on]
disk: hd0+ hd1+
>> SecBSD/amd64 BOOT 3.33
boot> boot hd1d:/bsd.rd

SecBSD boot loaders are documented in the architecture-specific boot(8) man pages.

Pre-installation Checklist

Before you start, you should have some idea what you want to end up with. A few things worth considering beforehand:

Machine name
Hardware installed and available:

Verify compatibility with your hardware. You may want to consult the platform-specific installation notes, especially if you're using one of the non-x86 CPU architectures. They contain detailed instructions and any possible caveats:

[amd64]

If wireless internet is your only option, does your card require additional firmware? If so, you'll need to manually download it to a USB drive or similar device, then use the fw_update(1) tool to enable it after SecBSD is installed.

Install method to be used
Desired disk layout:

Network settings, if not using DHCP:

Downloading SecBSD

The following installation images are available:

An SHA256 file containing checksums can be found in the same directory as the installation files. You can confirm that none of the downloaded files were mangled in transit using the sha256(1) command.

$ sha256 -C SHA256 miniroot*.img
(SHA256) minirootXX.img: OK

Or, if you're using an OS with the GNU coreutils:

$ sha256sum -c --ignore-missing SHA256
minirootXX.img: OK

However, this only checks for accidental corruption. You can use signify(1) and the SHA256.sig file to cryptographically verify the downloaded image.

$ signify -Cp /etc/signify/secbsd-XX-base.pub -x SHA256.sig miniroot*.img
Signature Verified
minirootXX.img: OK

Note that the signify package on other operating systems may not include the required public key, or it may be installed in another location.

The installXX.iso and installXX.img images do not contain an SHA256.sig file, so the installer will complain that it can't check the signature of the included sets:

Directory does not contain SHA256.sig. Continue without verification? [no]

This is because it would make no sense for the installer to verify them. If someone were to make a rogue installation image, they could certainly change the installer to say the files were legitimate.

If the image's signature has been verified beforehand, it is safe to answer "yes" at that prompt.

Creating Install Media

Flash Drive

A bootable USB flash drive can be created by attaching the target device and copying over the image with dd(1).

Using SecBSD, assuming the device was recognized as sd6:

# dd if=install*.img of=/dev/rsd6c bs=1m

Note that the raw I/O device is used, rsd6c rather than sd6c.

Details of this will vary on other platforms. The GNU version of dd will require bs=1M (note the capital M) instead. If you're using a different OS, be sure to select the appropriate device name: /dev/sdX on Linux or /dev/rdiskX on macOS for example.

CD-ROMs

You can create a bootable CD-ROM on SecBSD by using cdio(1).

# cdio tao cd*.iso

Performing a Simple Install

The installer is designed to install SecBSD in a very usable default configuration with a minimum of user intervention. In fact, you can often just hit <Enter> to get a good SecBSD install, moving your hands to the rest of the keyboard only to enter the root password.

After the dmesg(8) is shown, you will see the first installer question:

...
root on rd0a swap on rd0b dump on rd0b
erase ^?, werase ^W, kill ^U, intr ^C, status ^T

Welcome to the SecBSD/amd64 X.X installation program.
(I)nstall, (U)pgrade, (A)utoinstall or (S)hell?

Choose (I)nstall and follow the instructions.

File Sets

bsd
The kernel (required)
bsd.mp
The multi-processor kernel (only on some platforms)
bsd.rd
The ramdisk kernel
baseXX.tgz
The base system (required)
compXX.tgz
The compiler collection, headers and libraries
manXX.tgz
Manual pages
gameXX.tgz
Text-based games
xbaseXX.tgz
Base libraries and utilities for X11 (requires xshareXX.tgz)
xfontXX.tgz
Fonts used by X11
xservXX.tgz
X11's X servers
xshareXX.tgz
X11's man pages, locale settings and includes
New users are recommended to install all of them.

Some libraries from xbaseXX.tgz, like freetype or fontconfig, can be used outside of X by programs that manipulate text or graphics. Such programs will usually need fonts, either from xfontXX.tgz or font packages. For the sake of simplicity, the developers decided against maintaining a minimal xbaseXX.tgz set that would allow most non-X ports to run.

Performing a Full Disk Encryption Install

Much like RAID, full disk encryption in SecBSD is handled by the softraid(4) subsystem and bioctl(8) command. This section covers installing SecBSD to a single encrypted disk, and is a very similar process to the previous one. Note that "stacking" softraid modes (mirrored drives and encryption, for example) is not supported at this time.

Select (S)hell at the initial prompt.

Welcome to the SecBSD/amd64 X.X installation program.
(I)nstall, (U)pgrade, (A)utoinstall or (S)hell? s
From here, you'll be given a shell within the live environment to manipulate the disks. For this example, we will install to the sd0 SATA drive, erasing all of its previous contents.

Since the installer does not have many device nodes by default, make sure the /dev/sd0 device exists:

# cd /dev && sh MAKEDEV sd0
You may want to write random data to the drive first with something like the following:
# dd if=/dev/urandom of=/dev/rsd0c bs=1m
This can be a very time-consuming process, depending on the speed of your CPU and disk, as well as the size of the disk. If you don't write random data to the whole device, it may be possible for an adversary to deduce how much space is actually being used.

Next, initialize the disk with fdisk(8) and create the softraid partition with disklabel(8).

If you're booting from MBR, do:

# fdisk -iy sd0
If you use GPT for UEFI booting, do:
# fdisk -iy -g -b 960 sd0
Next, create the partition layout:
# disklabel -E sd0
Label editor (enter '?' for help at any prompt)
sd0> a a		
offset: [64]
size: [39825135] *
FS type: [4.2BSD] RAID
sd0*> w
sd0> q
No label changes.
We'll use the entire disk, but note that the encrypted device can be split up into multiple partitions as if it were a regular hard drive.

Now we can build the encrypted device on our "a" partition.

# bioctl -c C -l sd0a softraid0
New passphrase:
Re-type passphrase:
sd1 at scsibus2 targ 1 lun 0: <SECBSD, SR CRYPTO, 005> SCSI2 0/direct fixed
sd1: 19445MB, 512 bytes/sector, 39824607 sectors
softraid0: CRYPTO volume attached as sd1
Instead of a passphrase, you may want to use a keydisk.

Make sure the /dev/sd1 device is accounted for:

# cd /dev && sh MAKEDEV sd1
All data written to sd1 will now be encrypted with AES in XTS mode.

As in the previous example, we'll overwrite the first megabyte of our new pseudo-device.

# dd if=/dev/zero of=/dev/rsd1c bs=1m count=1
Type exit to return to the main installer, then choose this new device as the one for your installation.
[...]
Available disks are: sd0 sd1.
Which disk is the root disk? ('?' for details) [sd0] sd1
You will be prompted for the passphrase on startup, but all other operations should be handled transparently.

Using a Keydisk

As an alternative to using a passphrase, it's possible to use a key stored on a separate device (e.g. a USB stick) to unlock your encrypted disk.

Initialize your keydisk with fdisk(8), then use disklabel(8) to create a 1 MB RAID partition for the key data. If your keydisk is sd1 and the drive you want to encrypt is sd0, the output will look something like this:

# bioctl -c C -k sd1a -l sd0a softraid0
sd2 at scsibus3 targ 1 lun 0: <SECBSD, SR CRYPTO, 005> SCSI2 0/direct fixed
sd2: 19445MB, 512 bytes/sector, 39824607 sectors
softraid0: CRYPTO volume attached as sd2
You won't be prompted to enter a passphrase because you used a keydisk instead. The keydisk must be inserted at startup time.

You can backup and restore your keydisk using dd(1):

# dd bs=8192 skip=1 if=/dev/rsd1a of=backup-keydisk.img
# dd bs=8192 seek=1 if=backup-keydisk.img of=/dev/rsd1a

Security Updates

When a critical bug is found, the fix will be committed to the -current tree (and made available in snapshot builds) as soon as possible. From that point on, things are handled differently depending on whether the problem was in the SecBSD base system or a third party package. This section details how to keep your system up to date between releases.

For the SecBSD base system, security fixes are normally applied to the two most recent releases. There are four options:

For third party software installed via packages, fixes are normally only applied to the most recent release. There are three options:

Executing Commands as Another User

The doas(1) tool lets a system administrator permit certain users to run specific commands as another user. Regular users can run administrative commands, only being required to authenticate as themselves, without the need for the root password.

For example, if appropriately configured, the following command would display root's crontab(5) file:

$ doas -u root crontab -l
Commands invoked by doas(1) are logged to /var/log/secure by default. Check the doas.conf(5) manual for configuration examples.

Introduction

There are many applications one might want to use on an SecBSD system. To make this software easier to install and manage, it is ported to SecBSD and packaged. The aim of the package system is to keep track of which software gets installed, so that it may be easily updated or removed. In minutes, a large number of packages can be fetched and installed, with everything put in the right place.

The ports collection does not go through the same thorough security audit that is performed on the SecBSD base system. Although we strive to keep the quality of the packages high, we just do not have enough resources to ensure the same level of robustness and security.

The SecBSD ports team considers packages to be the goal of their porting work, not the ports themselves. In general, you are advised to use packages over building an application from ports.

Packages can be easily managed with the help of several utilities:

In order to run properly, application X may require that other applications Y and Z be installed. Application X is said to be dependent on these other applications, which is why Y and Z are called dependencies of X. In turn, Y may require other applications P and Q, and Z may require application R to function properly. This way, a whole dependency tree is formed.

Packages look like simple .tgz bundles. Basically they are just that, but there is one crucial difference: they contain some extra packing information. This information is used by pkg_add(1) for several purposes:

Installing Packages

The pkg_add(1) utility is used to install packages. If multiple flavors of a package exist, you will be prompted to choose which one you want to install.

# pkg_add rsync
Ambiguous: choose package for rsync
a       0: <None>
        1: rsync-3.1.2p0
        2: rsync-3.1.2p0-iconv
Your choice:

Here you would select 1 if you want the standard package or 2 if you need iconv support. You can also choose the flavor directly on the command line by using pkg_add rsync-- (for the default) or pkg_add rsync--iconv (for the iconv flavor).

It is possible to specify multiple package names on one line, which then all get installed at once, along with their dependencies. You may also specify the absolute location of a package, be it a local file or remote URL. Supported URL prefixes are http, https, ftp and scp.

For some packages, important additional information will be given about the configuration or use of the application.

# pkg_add jove
jove-4.16.0.73p0: ok
--- +jove-4.16.0.73p0 -------------------
See /usr/local/share/jove/README about changes to /etc/rc or
/etc/rc.local so that the system recovers jove files
on reboot after a system crash
Additionally, some packages provide configuration and other information in a file located in /usr/local/share/doc/pkg-readmes.

For your safety, if you are installing a package which you had installed earlier and removed, configuration files which have been modified will not be overwritten. The same is true for when you upgrade a package.

Sometimes you may encounter an error like the one in the following example:

# pkg_add xv
quirks-2.367 signed on 2017-10-03T11:21:28Z
xv-3.10ap4:jpeg-6bp3: ok
xv-3.10ap4:png-1.2.14p0: ok
xv-3.10ap4:tiff-3.8.2p0: ok
Can't install xv-3.10ap15 because of libraries
|library X11.16.1 not found
| not found anywhere
Direct dependencies for xv-3.10ap15 resolve to png-1.6.31 jasper-1.900.1p5 tiff-4.0.8p1 jpeg-1.5.1p0v0
Full dependency tree is png-1.6.31 tiff-4.0.8p1 jasper-1.900.1p5 jpeg-1.5.1p0v0

The packing information bundled in the package includes information about shared libraries that the package expects to be installed. If one of the required libraries can't be found, the package is not installed because it would not function anyway.

There are several things to check:

Updating Packages

Let's say you had an older version of unzip installed before upgrading this box to the latest SecBSD release. You can easily upgrade the package to the newer version like this:

# pkg_add -u unzip
unzip-5.52->unzip-5.52p0: ok
Read shared items: ok

When a package has dependencies, they are also examined for updates. Invoking pkg_add(1) with only the -u flag will try to update all installed packages. This is highly recommended over updating individual packages on their own.

Removing Packages

To remove a package, simply take the name of the package and use pkg_delete(1).

# pkg_delete screen
screen-4.0.3p6: ok
Read shared items: ok
Again, modified configuration files will not be removed. Unneeded dependencies can be trimmed by running pkg_delete -a at any time.

Network Configuration

Network configuration in SecBSD is done with text files in /etc. Typically, these settings are initially configured during the installation process.

Identifying and Setting Up Your Network Interfaces

Interfaces are named by the type of card, not the type of connection. For example, here's a dmesg(8) snippet for an Intel Fast Ethernet network card:
fxp0 at pci0 dev 10 function 0 "Intel 82557" rev 0x0c: irq 5, address 00:02:b3:2b:10:f7
inphy0 at fxp0 phy 1: i82555 10/100 media interface, rev. 4
This device uses the fxp(4) driver and is assigned the number 0 here.

You can find out what network interfaces have been identified by using the ifconfig(8) utility. The following command will show all network interfaces on a system.

$ ifconfig
lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 33200
        index 3 priority 0 llprio 3
        groups: lo
        inet 127.0.0.1 netmask 0xff000000
fxp0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
        lladdr 00:02:b3:2b:10:f7
        index 1 priority 0 llprio 3
        media: Ethernet autoselect (100baseTX full-duplex)
        status: active
        inet 10.0.0.38 netmask 0xffffff00 broadcast 10.0.0.255
enc0: flags=0<>
        index 2 priority 0 llprio 3
        groups: enc
        status: active
pflog0: flags=141<UP,RUNNING,PROMISC> mtu 33200
        index 4 priority 0 llprio 3
        groups: pflog
This sample shows only one physical Ethernet interface: fxp0. An IP is configured on it, hence the values inet 10.0.0.38 netmask 0xffffff00 broadcast 10.0.0.255. The UP and RUNNING flags are also set on it.

The netstart(8) script configures network interfaces at boot time using hostname.if(5) files, where "if" is replaced by the full name of each interface. The example above would use the file /etc/hostname.fxp0, containing the following options:

inet 10.0.0.38 255.255.255.0
This hostname.fxp0 file also has an interactive equivalent:
# ifconfig fxp0 10.0.0.38 255.255.255.0
Finally, you will notice several other interfaces come enabled by default. These are virtual interfaces that serve various functions. The following manual pages describe them: Other virtual interfaces can be added with ifconfig(8)'s create subcommand.

Wireless Networking

SecBSD has support for a number of wireless chipsets. Further supported devices can be found in usb(4) and pci(4). The precise extent of their support is described in the driver man pages.

The following cards support Host-based Access Point (HostAP) mode, permitting them to be used as a wireless access point:

The ifconfig(8) media subcommand shows media capabilities of network interfaces. For wireless devices, it displays supported 802.11a/b/g/n media modes and the supported operating modes (hostap, ibss, monitor). For example, to see media capabilities of interface ath0, type:

$ ifconfig ath0 media
In order to use some wireless cards, you will need to acquire firmware files with fw_update(1). Some manufacturers refuse to allow free distribution of their firmware, so it can't be included with SecBSD.

Another option to consider: use a conventional NIC and an external bridging wireless access point for your SecBSD-based firewall. This has the added advantage of letting you easily position the antenna where it is most effective, which is often not directly on the back of your firewall.

Configuring Your Wireless Adapter

Adapters based on supported chips can be used like any other network interface. To connect an SecBSD system to an existing wireless network, use the ifconfig(8) utility.

An example of a hostname.if(5) file for a wireless client might be:

nwid puffyuberalles wpakey passwordhere
dhcp
Or, for multiple access points:
join home-net wpakey passwordhere
join work-net wpakey passwordhere
join cafe-wifi
dhcp

Note that the dhcp keyword should be after the other configuration lines, as the network adapter will not be able to send a DHCP request until it is configured.

Trunking Your Wireless Adapter

Trunks are virtual interfaces consisting of one or more network interfaces. In this section, our example will be a laptop with a wired bge0 interface and a wireless iwn0 interface. We will build a trunk(4) interface using both of them.

To do this, we first activate the two physical ports, then assign them to trunk0.

# echo up > /etc/hostname.bge0
The wireless interface, however, needs a bit more configuration. It will need to attach to our wireless WPA-protected network:
$ cat /etc/hostname.iwn0
nwid puffynet wpakey mysecretkey
up
Now, our trunk interface is defined like this:
$ cat /etc/hostname.trunk0
trunkproto failover trunkport bge0
trunkport iwn0
dhcp
The trunk is set up in failover mode, so either interface can be used. If both are available, it will prefer the bge0 port, since that is the first one added to the trunk device.

Installation and configuration XFCE. By dev0x47

Table of contents:

Installing Xfce

$ doas pkg_add xfce consolekit2

Starting X

It is recommended to run X with the xenodm display manager, once it offers some important security benefits over the traditional startx[1] command. If xenodm(1) wasn't enabled during installation, it can be done so later like any other system daemon:
$ doas rcctl enable xenodm
$ doas rcctl start xenodm

Enabling Daemons

Logging and shutting down the computer

If your installation supports complete shutdown, clicking on the logout button on the panel will permit you to eighter logout, rebooting or halt the computer.

If your user is part of the operator group (can execute /sbin/shutdown) you should be able to shutdown/logout without further configuration. Otherwise, halting and rebooting require consolekit2code> and polkit: you will need to run a systemwide D-Bus service and pass --with-ck-launch argument to startxfce4.[2]

In order to manage daemons, do not alter rc.conf directly. Instead, use the rcctl utility to maintain the /etc/rc.conf.local file. This makes future upgrades easier as all the changes are in the one file that isn't touched during upgrade.[3]

First, enable, configure and start the apmd (advanced power management daemon) daemon:

# rcctl enable apmd
# rcctl set apmd flags -A
# rcctl start apmd
Secondly, enable and start the messagebus (dbus-daemon):
# rcctl enable messagebus
# rcctl start messagebus

Terminal, special characters and localized applications

If you use a particular non-ascii encoding and have problems seeing special characters in terminal (like accentued characters in french), you should properly configure the default encoding in terminal properties.[2]

Similarly, if you want localized graphical applications, add this line to your: .xsession before startxfce4:

export LC_MESSAGES=fr_FR.UTF-8
         
Where fr_FR is your language tag. See [4] for more information. Reboot. If you find any problems, read the .xsession-errors file log.

After logging in from xenodm the /etc/X11/xenodm/Xsession script checks whether there is a $HOME/.xsession script. In the simplest case, the user's ~/.xsession script will contain only one line specifying the preferred window manager to launch.[1]

The Xfce desktop environment is launched through the startxfce4 script. Simply add /usr/local/bin/startxfce4 to your .xsession file:[2]

$ echo "/usr/local/bin/startxfce4 --with-ck-launch" > ~/.xsession
Note that if you run a systemwide D-Bus service, have consolekit2/polkit installed and you don't pass the --with-ck-launch argument, you will not be able to shutdown/reboot the system.[2]

Conclusion

Reboot. If you find any problems, read the .xsession-errors file log.

See also

Installation and configuration i3. By dev0x47

Table of contents:

Installing i3

$ doas pkg_add i3

Starting X

As mentioned in FAQ11, it is recommended to run X with the xenodm(1) display manager, once it offers some important security benefits over the traditional startx(1) command. If xenodm(1) wasn't enabled during installation, it can be done so later like any other system daemon:
$ doas rcctl enable xenodm
$ doas rcctl start xenodm

Configuring X

After logging in from xenodm(1), the /etc/X11/xenodm/Xsession script checks whether there is a $HOME/.xsession script. In the simplest case, the user's ~/.xsession script will contain only one line specifying the preferred window manager to launch. It can contain any number of other commands, however:

echo "export ENV=$HOME/.kshrc
xsetroot -solid black &
xterm -bg black -fg white +sb &
i3" > ~/.xsession
Then copy some default configuration files:
$ doas cp /usr/local/share/examples/i3status/i3status.conf ~/.i3status.conf
$ doas cp /etc/X11/xenodm/Xresources ~/.Xresources
$ doas xrdb ~/.Xresources

Conclusion

After the first login, /usr/local/bin/i3-config-wizard will create its default onfiguration file ~/.config/i3/config