<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Jens@Fivesec on Medium]]></title>
        <description><![CDATA[Stories by Jens@Fivesec on Medium]]></description>
        <link>https://medium.com/@js_9757?source=rss-1d907e2b272e------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*tt91hWJpHi6nC95nC3R6NQ@2x.jpeg</url>
            <title>Stories by Jens@Fivesec on Medium</title>
            <link>https://medium.com/@js_9757?source=rss-1d907e2b272e------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 03:42:30 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@js_9757/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Network Fundamentals for Software Architects, Part 1: From Layer 2 to BGP]]></title>
            <link>https://medium.com/@js_9757/network-fundamentals-for-software-architects-part-1-from-layer-2-to-bgp-b9b43f371722?source=rss-1d907e2b272e------2</link>
            <guid isPermaLink="false">https://medium.com/p/b9b43f371722</guid>
            <category><![CDATA[networking]]></category>
            <category><![CDATA[data-center]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Jens@Fivesec]]></dc:creator>
            <pubDate>Wed, 04 Nov 2026 13:50:13 GMT</pubDate>
            <atom:updated>2026-11-04T13:50:13.620Z</atom:updated>
            <content:encoded><![CDATA[<p>BGP, EVPN, leaf-and-spine… lost in the buzzwords? Let’s build the network basics by hand, from MAC addresses to autonomous systems.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*lLeBk6cae7146IsF" /><figcaption>Photo by <a href="https://unsplash.com/@tvick?utm_source=medium&amp;utm_medium=referral">Taylor Vick</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><h3>Introduction</h3><p>You know the moment. You are a software architect on a hyperscaler or mini-scaler project, and you finally sit down with a network engineer to talk about the network design of the underlying data centre. Within ten minutes your head is spinning. BGP, L2VPN EVPN, leaf-and-spine architectures, network fabrics: the buzzwords fly across the table, and you nod along while quietly wondering what on earth they are talking about.</p><p>In this article, we will approach the topic slowly, and we start by getting to grips with the basics.</p><p>This is Part 1 of a two-part series. We build everything by hand in a small lab (based on <a href="https://www.gns3.com/">GNS3</a> ) made of Alpine Linux hosts and FRR routers, so you can follow along in your own terminal. Along the way we will cover:</p><ul><li><strong>Layer 2:</strong> MAC addresses, ARP, broadcast domains and subnetting</li><li><strong>Layer 3:</strong> routers, gateways and what really happens to a packet crossing two networks</li><li><strong>Routing with OSPF:</strong> how routers learn about each other’s networks</li><li><strong>The Internet, autonomous systems and BGP:</strong> how independent networks agree on who can reach what</li></ul><p>In Part 2 we take this knowledge into the data centre and finally decode leaf-and-spine, network fabrics and EVPN L2VPN (including VXLAN). No prior networking knowledge is required, only curiosity.</p><h3>Layer 2 Networking</h3><p>Let’s start with some fundamentals and explain the so-called Layer 2 (Data Link Layer) and Layer 3 (Network Layer) of the network stack. If you need a refresher on the layers, see the <a href="https://en.wikipedia.org/wiki/OSI_model">OSI model</a>.</p><p>To get going, we look at the following minimal topology:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/963/1*dJUCuP0GtLKPTBoVzIv4vg.png" /></figure><p>Two end devices, AlpineLinux-1 and AlpineLinux-2, are connected to Switch1 on ports e0 and e1. For this setup, the devices get the following IP addresses:</p><ul><li>AlpineLinux-1: 192.168.100.2/24</li><li>AlpineLinux-2: 192.168.100.3/24</li></ul><p>Both systems run on a Linux host system (Alpine). In the terminal, we assign the IP addresses:</p><pre><br># AlpineLinux-1<br>ip addr add 192.168.100.2/24 dev eth0<br><br># AlpineLinux-2<br>ip addr add 192.168.100.3/24 dev eth0</pre><p>Can the two systems talk to each other now? Yes, they can!</p><p>Let’s send a simple ICMP request with the ping command from AlpineLinux-1 and then take a look at the ARP table:</p><pre>ping 192.168.100.3<br><br>PING 192.168.100.3 (192.168.100.3): 56 data bytes<br>64 bytes from 192.168.100.3: seq=0 ttl=64 time=1.339 ms<br>64 bytes from 192.168.100.3: seq=1 ttl=64 time=0.583 ms<br>64 bytes from 192.168.100.3: seq=2 ttl=64 time=0.863 ms<br><br>ip neigh show<br>192.168.100.3 dev eth0 lladdr 02:42:9e:a4:06:00 ref 1 used 0/0/0 probes 4 REACHABLE</pre><p>So what just happened? Why is communication possible at all? We are in a so-called Layer 2 network, and MAC addresses (for example 02:42:9e:a4:06:00) play the essential role here. On Layer 2, <a href="https://en.wikipedia.org/wiki/Ethernet_frame">Ethernet frames</a> are transmitted, and IP addresses play only a secondary part. Our topology forms a fairly simple broadcast domain.</p><p>When we issue the ping command, the <a href="https://en.wikipedia.org/wiki/Address_Resolution_Protocol">Address Resolution Protocol (ARP)</a> sends out a broadcast request (to all devices) asking: “Who knows the MAC address of the device with IP address 192.168.100.3? Please send the answer to 192.168.100.2!” Our AlpineLinux-2 host replies with its MAC address.</p><p>The switch also takes note. It stores in its MAC address table (also known as the CAM table) which MAC address is connected to which port. For our lab setup, this gives us:</p><ul><li>Switch port e0: 02:42:e3:e1:e0:00 (AlpineLinux-1)</li><li>Switch port e1: 02:42:9e:a4:06:00 (AlpineLinux-2)</li></ul><p>The ARP tables on our Linux hosts are filled as well, so that not every single request has to start with a broadcast to the entire network:</p><pre># AlpineLinux-2<br>ip neigh show<br>192.168.100.2 dev eth0 lladdr 02:42:e3:e1:e0:00 used 0/0/0 probes 1 STALE<br><br># AlpineLinux-1<br>ip neigh show<br>192.168.100.3 dev eth0 lladdr 02:42:9e:a4:06:00 used 0/0/0 probes 4 STALE</pre><p>And just like that, we have built a small Layer 2 network.</p><h3>Splitting the network: a quick detour into subnetting</h3><p>In the next step, we want to separate our Layer 2 network further and cut it into two parts. For this, we extend the topology with two more hosts, AlpineLinux-3 and AlpineLinux-4.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QRkfMs7BZMnceZDR2ma5GQ.png" /></figure><p>Our goal is to run hosts 1 and 2 in a Layer 2 network of their own, and hosts 3 and 4 in another. To do so, we split our current /24 network, 192.168.100.0/24, into two networks. That means we need to get familiar with subnetting. What does /24 actually mean?</p><p>An IPv4 address consists of four blocks of one byte each, which together form a 32-bit address. The /24 says that the first 24 bits (the first three blocks) belong to the network part, and only the rest is available for addressing hosts. In binary notation:</p><pre># for /24<br>11111111.11111111.11111111.00000000<br><br>255.255.255.0</pre><p>This means our network has room for 2⁸ = 256 IP addresses. One address is reserved for the network itself (192.168.100.0) and one for the broadcast address (192.168.100.255), so we can supply 254 hosts (clients) with an IP address.</p><p>If we want to cut our network into two equally sized halves, we increase the subnet mask by one bit to /25, which gives us the following netmask:</p><pre># for /25<br>11111111.11111111.11111111.10000000<br><br>255.255.255.128</pre><p>This results in two networks:</p><ul><li>192.168.100.0 to 192.168.100.127 (network address: 192.168.100.0, broadcast: 192.168.100.127)</li><li>192.168.100.128 to 192.168.100.255 (network address: 192.168.100.128, broadcast: 192.168.100.255)</li></ul><p>For our hosts, this means:</p><ul><li>AlpineLinux-1: 192.168.100.2/25</li><li>AlpineLinux-2: 192.168.100.3/25</li><li>AlpineLinux-3: 192.168.100.129/25</li><li>AlpineLinux-4: 192.168.100.130/25</li></ul><p>A test from AlpineLinux-4 shows that the networks have been separated successfully into two subnets:</p><pre># from AlpineLinux-4<br># ping AlpineLinux-3<br>ping 192.168.100.129<br><br>ip neigh show<br>192.168.100.129 dev eth0 lladdr 02:42:de:8e:f4:00 ref 1 used 0/0/0 probes 1 REACHABLE<br><br># ping AlpineLinux-1<br>ping 192.168.100.2<br>PING 192.168.100.2 (192.168.100.2): 56 data bytes<br>ping: sendto: Network unreachable</pre><p>Communication between the two networks is not possible without a router (that is, Layer 3 communication). To make this clearer:</p><pre># from AlpineLinux-4<br>ip route<br>192.168.100.128/25 dev eth0 scope link  src 192.168.100.130<br><br># shows the network 192.168.100.128/25 is reachable<br><br>ip route get 192.168.100.2/25<br>ip: RTNETLINK answers: Network unreachable<br># shows network 192.168.100.2/25 is unreachable</pre><p>In the next section, we extend our topology and build the Layer 3 network.</p><h3>Layer 3 Networking</h3><p>We extend our topology with a second switch and a router (a plain AlpineLinux machine).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jcoNp-7CT1dwKc9Qi4twXQ.png" /></figure><p>Our host systems get the following IP addresses:</p><ul><li>AlpineLinux-1: 192.168.100.2/25</li><li>AlpineLinux-2: 192.168.100.3/25</li><li>AlpineLinux-3: 192.168.100.130/25</li><li>AlpineLinux-4: 192.168.100.131/25</li></ul><p>Our router gets these IP addresses:</p><ul><li>Interface eth0: 192.168.100.1/25</li><li>Interface eth1: 192.168.100.129/25</li></ul><pre># on AlpineLinuxRouter<br><br>ip addr add 192.168.100.1/25 dev eth0<br>ip addr add 192.168.100.129/25 dev eth1<br>ip a s<br>1: lo: &lt;LOOPBACK,UP,LOWER_UP&gt; mtu 65536 qdisc noqueue state UNKNOWN qlen 1000<br>    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00<br>    inet 127.0.0.1/8 scope host lo<br>       valid_lft forever preferred_lft forever<br>    inet6 ::1/128 scope host<br>       valid_lft forever preferred_lft forever<br>86: eth0: &lt;BROADCAST,MULTICAST,UP,LOWER_UP&gt; mtu 65521 qdisc fq_codel state UNKNOWN qlen 1000<br>    link/ether 02:42:ba:c2:d6:00 brd ff:ff:ff:ff:ff:ff<br>    inet 192.168.100.1/25 scope global eth0<br>       valid_lft forever preferred_lft forever<br>    inet6 fe80::42:baff:fec2:d600/64 scope link<br>       valid_lft forever preferred_lft forever<br>87: eth1: &lt;BROADCAST,MULTICAST,UP,LOWER_UP&gt; mtu 65521 qdisc fq_codel state UNKNOWN qlen 1000<br>    link/ether 02:42:ba:c2:d6:01 brd ff:ff:ff:ff:ff:ff<br>    inet 192.168.100.129/25 scope global eth1<br>       valid_lft forever preferred_lft forever<br>    inet6 fe80::42:baff:fec2:d601/64 scope link<br>       valid_lft forever preferred_lft forever</pre><p>Our hosts still have no gateway, that is, no way out of their own network. To fix this, we set 192.168.100.1 as the gateway for hosts 1 and 2, and 192.168.100.129 for hosts 3 and 4.</p><p>If we now send a ping from AlpineLinux-4 to AlpineLinux-1, we get a reply. Whoops?! How is that possible?</p><pre># from Alpine Linux-4<br>ping 192.168.100.2<br>PING 192.168.100.2 (192.168.100.2): 56 data bytes<br>64 bytes from 192.168.100.2: seq=0 ttl=63 time=1.494 ms<br>64 bytes from 192.168.100.2: seq=1 ttl=63 time=1.238 ms</pre><p>A whole lot of steps happen here:</p><ol><li>AlpineLinux-4 compares its own IP address and netmask (192.168.100.131/25) with the destination IP address and netmask (192.168.100.2/25). The result: the destination is not in its own subnet.</li><li>AlpineLinux-4 looks up its gateway (default gateway via 192.168.100.129). It asks for the router’s MAC address via ARP and sends the Ethernet frame to our router.</li><li>AlpineLinuxRouter receives the Ethernet frame. It looks up the destination IP address 192.168.100.2 in its internal routing table, and eth0 with the network address 192.168.100.0/25 is a match. Via an ARP request on interface eth0, the router also determines the MAC address of our destination (192.168.100.2).</li><li>AlpineLinuxRouter builds a new Ethernet frame. The source and destination IP addresses stay the same, but the router puts its own MAC address in as the source MAC address. The frame is received by AlpineLinux-1.</li><li>The return path from AlpineLinux-1 to AlpineLinux-4 follows the same pattern.</li></ol><p>And with that, we have established Layer 3 traffic between two networks. In our case, though, the router has only two interfaces. How do we connect several networks with one another? In the next step, we extend our lab with a second router and take a closer look at routing protocols.</p><h3>Layer 3 Routing with OSPF</h3><p>We rebuild our topology as follows:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/766/1*kDUUQxSiP0zPXLnjBUXZyw.png" /></figure><p>The network is set up like this:</p><ul><li>AlpineLinux-1: IP address 192.168.100.2/24, gateway 192.168.100.1</li><li>AlpineLinux-2: IP address 192.168.200.2/24, gateway 192.168.200.1</li><li>frr-1: eth0 192.168.100.1/24, eth1 172.16.10.10/16</li><li>frr-2: eth0 192.168.200.1/24, eth1 172.16.10.11/16</li></ul><p>FRR? What on earth is that? <a href="https://frrouting.org/">FRRouting</a> (FRR, formerly Free Range Routing) is a free and open-source internet routing suite for Linux. Among other things, FRR supports routing protocols such as OSPF, BGP, IS-IS and RIP, and it turns our Linux machine into a fully fledged router. Isn’t that cool?!</p><p>The 172.16.0.0/16 network is a so-called transit network. Its only job is to connect our routers with each other in a network of their own.</p><p>Once the IP addresses are assigned, traffic inside the individual networks (192.168.100.0/24, 192.168.200.0/24 and 172.16.0.0/16) works as before. Remember the Layer 2 section? Trying to reach our AlpineLinux-2 host from AlpineLinux-1, however, does not work yet.</p><pre># from AlpineLinux-1<br>ping 192.168.200.2<br>PING 192.168.200.2 (192.168.200.2): 56 data bytes<br>^C<br>--- 192.168.200.2 ping statistics ---<br>5 packets transmitted, 0 packets received, 100% packet loss<br><br># route tracing<br>traceroute 192.168.200.2<br>traceroute to 192.168.200.2 (192.168.200.2), 30 hops max, 46 byte packets<br> 1  192.168.100.1 (192.168.100.1)  0.527 ms !N  0.380 ms !N  0.208 ms !N</pre><p>As we can see, the journey ends at our router frr-1. Why, actually? Quite simply, frr-1 does not know the network 192.168.200.0/24. How could it? First, router frr-2 would have to share its network information with router frr-1.</p><p>That is exactly what we want to achieve in the next step with the OSPF routing protocol. It is part of the FRR suite and can therefore be configured right away.</p><p>OSPF (Open Shortest Path First) is a so-called dynamic link-state routing protocol for networks within an autonomous system (AS). We will clear up what an autonomous system is later!</p><p>Link-state means that every router announces its links (neighbours) in messages to all the routers it is connected to. As a result, every router knows the entire topology and is able to calculate the shortest routing paths on its own.</p><p>We configure our FRR routers as follows:</p><pre># Edit /etc/frr/daemons<br># Switch entry ospfd=no to ospfd=yes<br># restart frr<br> /usr/lib/frr/frrinit.sh restart <br><br># show frr daemones<br>vtysh -c &quot;show daemons&quot;<br>mgmtd zebra ospfd watchfrr staticd<br></pre><p>What matters here is that the ospfd daemon is running.</p><p>The OSPF configuration for frr-1 looks like this. We edit the file /etc/frr/frr.conf and append the following to the end of the file:</p><pre>router ospf<br> ospf router-id 1.1.1.1<br> network 192.168.100.0/24 area 10<br> network 172.16.10.0/16 area 10<br>exit</pre><p>Adjusted for frr-2:</p><pre>router ospf<br> ospf router-id 2.2.2.2<br> network 192.168.200.0/24 area 10<br> network 172.16.10.0/16 area 10<br>exit</pre><p>Afterwards, we restart FRR once on both systems (/usr/lib/frr/frrinit.sh restart) and open the FRR terminal via vtysh.</p><p><strong>OSPF neighbour on frr-1</strong></p><pre>ubuntu-26-04-frr-1# show ip ospf neighbor<br><br>Neighbor ID     Pri State           Up Time         Dead Time Address         Interface                        RXmtL RqstL DBsmL<br>2.2.2.2           1 Full/Backup     27.385s           33.903s 172.16.10.11    eth1:172.16.10.10                    0     0     0<br><br>ubuntu-26-04-frr-1#</pre><p><strong>OSPF neighbour on frr-2</strong></p><pre>ubuntu-26-04-frr-2# show ip ospf neighbor<br><br>Neighbor ID     Pri State           Up Time         Dead Time Address         Interface                        RXmtL RqstL DBsmL<br>1.1.1.1           1 Full/DR         24.075s           35.925s 172.16.10.10    eth1:172.16.10.11                    0     0     0</pre><p>Both routers have now exchanged their network information, so communication from network 192.168.100.0/24 to 192.168.200.0/24, and the other way round, is possible. Not that hard, is it?</p><pre># ping from AlpineLinux-1<br>ping 192.168.200.2<br>PING 192.168.200.2 (192.168.200.2): 56 data bytes<br>64 bytes from 192.168.200.2: seq=0 ttl=62 time=1.355 ms<br>64 bytes from 192.168.200.2: seq=1 ttl=62 time=1.637 ms<br>64 bytes from 192.168.200.2: seq=2 ttl=62 time=1.442 ms<br>^C<br>--- 192.168.200.2 ping statistics ---<br>3 packets transmitted, 3 packets received, 0% packet loss<br>round-trip min/avg/max = 1.355/1.478/1.637 ms<br>/ #</pre><pre># ping from AlpineLinux-2<br>/ # ping 192.168.100.2<br>PING 192.168.100.2 (192.168.100.2): 56 data bytes<br>64 bytes from 192.168.100.2: seq=0 ttl=62 time=1.217 ms<br>64 bytes from 192.168.100.2: seq=1 ttl=62 time=1.770 ms<br>^C<br>--- 192.168.100.2 ping statistics ---<br>2 packets transmitted, 2 packets received, 0% packet loss<br>round-trip min/avg/max = 1.217/1.493/1.770 ms<br>/ #</pre><h3>The Internet, Autonomous Systems and BGP</h3><p>The Internet is one single, big network, right? Far from it! It consists of thousands of independent networks, the so-called autonomous systems (AS). These are run by internet service providers (Deutsche Telekom, …), cloud operators (AWS, GCP, …), large corporations and so on, each with interests of their own. Every AS has its own IP address ranges, and these are exchanged between the autonomous systems to guarantee reachability and communication across them.</p><p>Here is an example, using an IP address belonging to AWS:</p><pre>whois -h whois.cymru.com 23.20.0.3<br>AS      | IP               | AS Name<br>14618   | 23.20.0.3        | AMAZON-AES - Amazon.com, Inc., US</pre><p>In this case, AWS owns the autonomous system with the number 14618.</p><p>But how do the operators of autonomous systems exchange their network information? This is exactly where the <a href="https://en.wikipedia.org/wiki/Border_Gateway_Protocol">Border Gateway Protocol (BGP)</a> comes into play. BGP is used to connect autonomous systems with each other. It belongs to the family of path-vector protocols, which means that every route carries the list of autonomous systems it has passed through (the AS_PATH). BGP never exchanges topology information, only the reachability of networks.</p><h3>A small example of BGP and autonomous systems</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/827/1*96pv_11Id0FSqD1TvXZHKQ.png" /></figure><ol><li>AS 65003 tells its neighbours (AS 65004 and AS 65002) that the network 203.14.15.0/24 is reachable via AS 65003 (AS_PATH = 65003).</li><li>AS 65002 receives this information and passes it on to its neighbour (AS 65001). The important part: AS 65002 prepends its own ASN (autonomous system number) to the path. The result is AS_PATH = 65002 65003 for network 203.14.15.0/24.</li><li>AS 65004 does exactly the same.</li><li>AS 65001 receives two AS paths of length 2 from its two neighbours (AS 65002 and AS 65004). From the point of view of AS 65001, the network 203.14.15.0/24 is therefore reachable via AS 65002 and via AS 65004.</li></ol><p>Worth mentioning: AS 65001 will in turn pass network information on to its neighbours. Doesn’t that cause a loop? Not at all! BGP is smart enough to notice when its own ASN is already contained in the AS_PATH, and it simply discards that route. A loop can never form. This is, more or less, the central idea of a path-vector protocol.</p><p>BGP uses TCP (port 179) to exchange routing information, which guarantees reliability and ordering.</p><h3>Building the BGP Lab</h3><p>We build a lab topology for this as well.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TV2B-PYXByMgT2WUCmY4dw.png" /></figure><p>Our autonomous systems are to announce the following networks:</p><ul><li>AS65001: 10.10.0.0/16</li><li>AS65002: 172.16.0.0/16</li><li>AS65003: 192.168.10.0/24</li></ul><p>Our hosts get these IP addresses:</p><ul><li>AlpineLinux-1: 10.10.10.100/16 and FRR-1: 10.10.1.1/16</li><li>AlpineLinux-2: 172.16.10.100/16 and FRR-2: 172.16.1.1/16</li><li>AlpineLinux-3: 192.168.10.100/24 and FRR-3: 192.168.10.1/24</li></ul><p>This raises the question of how the BGP routers are actually connected to each other. As a rule, we are talking about a so-called peering network. In practice, these can be direct connections between providers or AS owners, <a href="https://en.wikipedia.org/wiki/Internet_exchange_point">Internet Exchange Points (IXP)</a>, or connections via other transport providers.</p><p>For our lab, we use the range 10.200.100.0/24 as the peering network, carved into /31 point-to-point links. This gives our BGP routers (the FRRs) the following addresses in the peering network:</p><ul><li>FRR-1 (10.200.100.4/31) to FRR-2 (10.200.100.5/31)</li><li>FRR-1 (10.200.100.6/31) to FRR-3 (10.200.100.7/31)</li><li>FRR-2 (10.200.100.8/31) to FRR-3 (10.200.100.9/31)</li></ul><pre># AlpineLinux-1<br><br>ip addr add 10.10.10.100/16 dev eth0<br>ip route add default via 10.10.1.1<br><br># AlpineLinux-2<br><br>ip addr add 172.16.10.100/16 dev eth0<br>ip route add default via 172.16.1.1<br><br># AlpineLinux-3<br><br>ip addr add 192.168.10.100/24 dev eth0<br>ip route add default via 192.168.10.1<br><br># FRR-1<br><br>ip addr add 10.10.1.1/16 dev eth0<br><br>ip addr add 10.200.100.4/31 dev eth1<br>ip addr add 10.200.100.6/31 dev eth2<br><br><br># FRR-2<br><br>ip addr add 172.16.1.1/16 dev eth0<br><br>ip addr add 10.200.100.5/31 dev eth1<br>ip addr add 10.200.100.8/31 dev eth2<br><br><br># FRR-3<br><br>ip addr add 192.168.10.1/24 dev eth2<br><br>ip addr add 10.200.100.7/31 dev eth0<br>ip addr add 10.200.100.9/31 dev eth1<br><br></pre><p>We now have connectivity between our BGP routers, and between each of our Alpine hosts and its router. In the next step, it is time to configure BGP and exchange the network information.</p><h3>Configuring BGP</h3><p>First, we make sure that /etc/frr/daemons on our FRR hosts has ospfd=no and bgpd=yes:</p><pre>osbpfd=no<br>bgpd=yes</pre><p>Afterwards, we restart the FRR service once:</p><pre>/usr/lib/frr/frrinit.sh restart</pre><p>Then we add the following entries to /etc/frr/frr.conf.</p><p>FRR-1</p><pre>!frr-1 /etc/frr/frr.conf<br>router bgp 65001<br> bgp router-id 10.255.255.1<br> no bgp ebgp-requires-policy<br><br> neighbor 10.200.100.5 remote-as 65002<br> neighbor 10.200.100.7 remote-as 65003<br><br> address-family ipv4 unicast<br>  network 10.10.0.0/16<br>  network 10.255.255.1/32<br>  maximum-paths 2<br> exit-address-family</pre><p>FRR-2</p><pre>!frr-2 /etc/frr/frr.conf<br>router bgp 65002<br> bgp router-id 10.255.255.2<br> no bgp ebgp-requires-policy<br><br> neighbor 10.200.100.4 remote-as 65001<br> neighbor 10.200.100.9 remote-as 65003<br><br> address-family ipv4 unicast<br>  network 172.16.0.0/16<br>  network 10.255.255.2/32<br>  maximum-paths 2<br> exit-address-family</pre><p>FRR-3</p><pre>!frr-3 /etc/frr/frr.conf<br>router bgp 65003<br> bgp router-id 10.255.255.3<br> no bgp ebgp-requires-policy<br><br> neighbor 10.200.100.6 remote-as 65001<br> neighbor 10.200.100.8 remote-as 65002<br><br> address-family ipv4 unicast<br>  network 192.168.10.0/24<br>  network 10.255.255.3/32<br>  maximum-paths 2<br> exit-address-family</pre><p>Before we restart or reload the FRR service, we bind the router IDs, as IP addresses, to the respective loopback interfaces:</p><pre># FRR-1<br>ip addr add 10.255.255.1/32 dev lo<br><br># FRR-2<br>ip addr add 10.255.255.2/32 dev lo<br><br># FRR-3<br>ip addr add 10.255.255.3/32 dev lo</pre><p>Why, actually? The loopback (lo) interface is a purely logical interface and is always reachable. It gives us a clear and unambiguous identity for each of our BGP routers. In the context we will get to later, it also adds resilience, because a logical interface cannot fail (unlike a physical one).</p><p>Afterwards, we restart the FRR service with /usr/lib/frr/frrinit.sh restart. Now we take a look at the BGP information on all FRR devices. The commands are:</p><pre>vtysh -c &quot;show ip bgp summary&quot;<br>vtysh -c &quot;show ip bgp&quot;</pre><p>It should look like this.</p><p>FRR-1</p><pre>root@ubuntu-26-04-frr-1:/# vtysh -c &quot;show ip bgp summary&quot;<br><br>IPv4 Unicast Summary:<br>BGP router identifier 10.255.255.1, local AS number 65001 VRF default vrf-id 0<br>BGP table version 10<br>RIB entries 11, using 1408 bytes of memory<br>Peers 2, using 47 KiB of memory<br><br>Neighbor        V         AS   MsgRcvd   MsgSent   TblVer  InQ OutQ  Up/Down State/PfxRcd   PfxSnt Desc<br>10.200.100.5    4      65002        11        12       10    0    0 00:00:11            4        6 N/A<br>10.200.100.7    4      65003        15        10       10    0    0 00:00:07            4        6 N/A<br><br>Total number of neighbors 2<br>root@ubuntu-26-04-frr-1:/# vtysh -c &quot;show ip bgp&quot;<br>BGP table version is 10, local router ID is 10.255.255.1, vrf id 0<br>Default local pref 100, local AS 65001<br>Status codes:  s suppressed, d damped, h history, u unsorted, * valid, &gt; best, = multipath,<br>               i internal, r RIB-failure, S Stale, R Removed<br>Nexthop codes: @NNN nexthop&#39;s vrf id, &lt; announce-nh-self<br>Origin codes:  i - IGP, e - EGP, ? - incomplete<br>RPKI validation codes: V valid, I invalid, N Not found<br><br>     Network          Next Hop            Metric LocPrf Weight Path<br> *&gt;  10.10.0.0/16     0.0.0.0                  0         32768 i<br> *&gt;  10.255.255.1/32  0.0.0.0                  0         32768 i<br> *&gt;  10.255.255.2/32  10.200.100.5             0             0 65002 i<br> *                    10.200.100.7                           0 65003 65002 i<br> *&gt;  10.255.255.3/32  10.200.100.7             0             0 65003 i<br> *                    10.200.100.5                           0 65002 65003 i<br> *&gt;  172.16.0.0/16    10.200.100.5             0             0 65002 i<br> *                    10.200.100.7                           0 65003 65002 i<br> *&gt;  192.168.10.0/24  10.200.100.7             0             0 65003 i<br> *                    10.200.100.5                           0 65002 65003 i<br><br>Displayed 6 routes and 10 total paths</pre><p>FRR-2</p><pre>root@ubuntu-26-04-frr-2:/# vtysh -c &quot;show ip bgp summary&quot;<br><br>IPv4 Unicast Summary:<br>BGP router identifier 10.255.255.2, local AS number 65002 VRF default vrf-id 0<br>BGP table version 6<br>RIB entries 11, using 1408 bytes of memory<br>Peers 2, using 47 KiB of memory<br><br>Neighbor        V         AS   MsgRcvd   MsgSent   TblVer  InQ OutQ  Up/Down State/PfxRcd   PfxSnt Desc<br>10.200.100.4    4      65001         6         6        6    0    0 00:00:34            4        6 N/A<br>10.200.100.9    4      65003        12         8        6    0    0 00:00:30            4        6 N/A<br><br>Total number of neighbors 2<br>root@ubuntu-26-04-frr-2:/# vtysh -c &quot;show ip bgp&quot;<br>BGP table version is 6, local router ID is 10.255.255.2, vrf id 0<br>Default local pref 100, local AS 65002<br>Status codes:  s suppressed, d damped, h history, u unsorted, * valid, &gt; best, = multipath,<br>               i internal, r RIB-failure, S Stale, R Removed<br>Nexthop codes: @NNN nexthop&#39;s vrf id, &lt; announce-nh-self<br>Origin codes:  i - IGP, e - EGP, ? - incomplete<br>RPKI validation codes: V valid, I invalid, N Not found<br><br>     Network          Next Hop            Metric LocPrf Weight Path<br> *&gt;  10.10.0.0/16     10.200.100.4             0             0 65001 i<br> *                    10.200.100.9                           0 65003 65001 i<br> *&gt;  10.255.255.1/32  10.200.100.4             0             0 65001 i<br> *                    10.200.100.9                           0 65003 65001 i<br> *&gt;  10.255.255.2/32  0.0.0.0                  0         32768 i<br> *&gt;  10.255.255.3/32  10.200.100.9             0             0 65003 i<br> *                    10.200.100.4                           0 65001 65003 i<br> *&gt;  172.16.0.0/16    0.0.0.0                  0         32768 i<br> *&gt;  192.168.10.0/24  10.200.100.9             0             0 65003 i<br> *                    10.200.100.4                           0 65001 65003 i<br><br>Displayed 6 routes and 10 total paths<br>root@ubuntu-26-04-frr-2:/#</pre><p>FRR-3</p><pre>root@ubuntu-26-04-frr-3:/# vtysh -c &quot;show ip bgp summary&quot;<br><br>IPv4 Unicast Summary:<br>BGP router identifier 10.255.255.3, local AS number 65003 VRF default vrf-id 0<br>BGP table version 6<br>RIB entries 11, using 1408 bytes of memory<br>Peers 2, using 47 KiB of memory<br><br>Neighbor        V         AS   MsgRcvd   MsgSent   TblVer  InQ OutQ  Up/Down State/PfxRcd   PfxSnt Desc<br>10.200.100.6    4      65001         6         6        6    0    0 00:00:39            4        6 N/A<br>10.200.100.8    4      65002         6         6        6    0    0 00:00:39            4        6 N/A<br><br>Total number of neighbors 2<br>root@ubuntu-26-04-frr-3:/# vtysh -c &quot;show ip bgp&quot;<br>BGP table version is 6, local router ID is 10.255.255.3, vrf id 0<br>Default local pref 100, local AS 65003<br>Status codes:  s suppressed, d damped, h history, u unsorted, * valid, &gt; best, = multipath,<br>               i internal, r RIB-failure, S Stale, R Removed<br>Nexthop codes: @NNN nexthop&#39;s vrf id, &lt; announce-nh-self<br>Origin codes:  i - IGP, e - EGP, ? - incomplete<br>RPKI validation codes: V valid, I invalid, N Not found<br><br>     Network          Next Hop            Metric LocPrf Weight Path<br> *&gt;  10.10.0.0/16     10.200.100.6             0             0 65001 i<br> *                    10.200.100.8                           0 65002 65001 i<br> *&gt;  10.255.255.1/32  10.200.100.6             0             0 65001 i<br> *                    10.200.100.8                           0 65002 65001 i<br> *&gt;  10.255.255.2/32  10.200.100.8             0             0 65002 i<br> *                    10.200.100.6                           0 65001 65002 i<br> *&gt;  10.255.255.3/32  0.0.0.0                  0         32768 i<br> *&gt;  172.16.0.0/16    10.200.100.8             0             0 65002 i<br> *                    10.200.100.6                           0 65001 65002 i<br> *&gt;  192.168.10.0/24  0.0.0.0                  0         32768 i<br><br>Displayed 6 routes and 10 total paths<br>root@ubuntu-26-04-frr-3:/# </pre><p>All network and routing information has been exchanged successfully between the autonomous systems. On our AlpineLinux hosts, we run the following ping tests:</p><pre>#AlpineLinux-1<br>ping -c 4 10.10.1.1<br>ping -c 4 172.16.10.100<br>ping -c 4 192.168.10.100<br><br><br>##AlpineLinux-2<br>ping -c 4 172.16.1.1<br>ping -c 4 10.10.10.100<br>ping -c 4 192.168.10.100<br><br><br>#AlpineLinux-3<br>ping -c 4 192.168.10.1<br>ping -c 4 10.10.10.100<br>ping -c 4 172.16.10.100</pre><p>Voilà! Our three autonomous systems can communicate with each other.</p><h3>What happens when a link fails?</h3><p>But what happens if we cut the connection between FRR-1 (AS65001) and FRR-3 (AS65003)? According to the path-vector protocol, and to the way BGP passes routes on to its direct neighbours, communication from AS65001 to AS65003 should keep working via AS65002, shouldn’t it?</p><p>We can test this by simply disabling the corresponding interface on FRR-1 (eth2):</p><pre># FRR-1<br>ip link set eth2 down</pre><p>Looking at the BGP table, we see that AS65003 is no longer directly reachable. For comparison:</p><p><strong>Before the interface shutdown</strong></p><pre>     Network          Next Hop            Metric LocPrf Weight Path<br> *&gt;  10.10.0.0/16     0.0.0.0                  0         32768 i<br> *&gt;  10.255.255.1/32  0.0.0.0                  0         32768 i<br> *&gt;  10.255.255.2/32  10.200.100.5             0             0 65002 i<br> *                    10.200.100.7                           0 65003 65002 i<br> *&gt;  10.255.255.3/32  10.200.100.7             0             0 65003 i<br> *                    10.200.100.5                           0 65002 65003 i<br> *&gt;  172.16.0.0/16    10.200.100.5             0             0 65002 i<br> *                    10.200.100.7                           0 65003 65002 i<br> *&gt;  192.168.10.0/24  10.200.100.7             0             0 65003 i<br> *                    10.200.100.5                           0 65002 65003 i</pre><p><strong>After the interface shutdown</strong></p><pre>     Network          Next Hop            Metric LocPrf Weight Path<br> *&gt;  10.10.0.0/16     0.0.0.0                  0         32768 i<br> *&gt;  10.255.255.1/32  0.0.0.0                  0         32768 i<br> *&gt;  10.255.255.2/32  10.200.100.5             0             0 65002 i<br> *&gt;  10.255.255.3/32  10.200.100.5                           0 65002 65003 i<br> *&gt;  172.16.0.0/16    10.200.100.5             0             0 65002 i<br> *&gt;  192.168.10.0/24  10.200.100.5                           0 65002 65003 i</pre><p>The direct path</p><pre>*&gt;  192.168.10.0/24  10.200.100.7             0             0 65003 i</pre><p>is no longer available. Traffic between AS1 (65001) and AS3 (65003) now flows via AS2 (65002).</p><h3>Summary</h3><p>We started with two hosts and a switch, and ended with three autonomous systems that reroute around a broken link on their own. Here is what we learned along the way:</p><ul><li><strong>Layer 2</strong> moves Ethernet frames between MAC addresses inside one broadcast domain. ARP translates IP addresses into MAC addresses, and the switch learns which MAC sits behind which port.</li><li><strong>Subnetting</strong> splits one network into several. Hosts in different subnets cannot talk to each other without a router.</li><li><strong>Layer 3</strong> is where routers come in. A host sends traffic for foreign networks to its default gateway, and the router forwards it with a new Ethernet frame.</li><li><strong>Routing protocols</strong> save us from maintaining routes by hand. Routers learn about each other’s networks and react when things change.</li><li><strong>Loopback interfaces</strong> give a router a stable identity that does not depend on any physical link.</li></ul><p>OSPF and BGP both solve the problem of sharing reachability, but they work very differently</p><p><strong>OSPF</strong></p><ul><li><strong>Type</strong>: Link-State</li><li><strong>Typical Scope</strong>: Inside one autonomous system</li><li><strong>What is exchanged</strong>: Links, so every router can calculate the full topology</li><li><strong>Loop prevention</strong>: Every router calculates the shortest path from the same topology</li><li><strong>Transport</strong>: Runs directly on IP</li></ul><p><strong>BGP</strong></p><ul><li><strong>Type</strong>: Path-Vector</li><li><strong>Typical Scope</strong>: Between autonomous systems</li><li><strong>What is exchanged</strong>: Reachability and the AS_PATH, never topology</li><li><strong>Loop prevention</strong>: A router discards routes containing its own ASN</li><li><strong>Transport</strong>: TCP, port 179</li></ul><p>The link-failure test shows the real strength of BGP: no one told AS65001 how to reach AS65003 via AS65002. It worked that out from the paths its neighbours announced.</p><h3>What’s next</h3><p>BGP was built to connect the networks of the Internet. So why do network engineers use it inside data centres, and what do leaf-and-spine, network fabrics and EVPN L2VPN have to do with it? Remember that Layer 2 network we started with? In <strong>Part 2</strong>, we take it into the data centre, stretch it across many racks and finally decode those buzzwords. See you there!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b9b43f371722" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building an SMTP Honeypot That Says Yes to Everything]]></title>
            <link>https://medium.com/@js_9757/building-an-smtp-honeypot-that-says-yes-to-everything-42814bdf4935?source=rss-1d907e2b272e------2</link>
            <guid isPermaLink="false">https://medium.com/p/42814bdf4935</guid>
            <category><![CDATA[cyber-security-awareness]]></category>
            <category><![CDATA[smtp]]></category>
            <category><![CDATA[bots]]></category>
            <category><![CDATA[hacking]]></category>
            <category><![CDATA[cybersecurity]]></category>
            <dc:creator><![CDATA[Jens@Fivesec]]></dc:creator>
            <pubDate>Thu, 08 Oct 2026 19:37:23 GMT</pubDate>
            <atom:updated>2026-10-08T19:37:23.825Z</atom:updated>
            <content:encoded><![CDATA[<p>A fake open relay in under 300 lines of Kotlin, built with Spring Boot and Apache James. It accepts every message, delivers none, and logs it all. Saying yes turned out to be easy. Saying yes safely was the real work.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*As4VvGjO1DfuuKUy" /><figcaption>Photo by <a href="https://unsplash.com/@brett_jordan?utm_source=medium&amp;utm_medium=referral">Brett Jordan</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>Here is a complete conversation with my honeypot. To the client on the other end, it looks like a mail server that’s a little too helpful:</p><pre>220 &lt;hostname&gt; SMTP Server (JAMES SMTP Protocols Server) ready<br>EHLO spammer.example<br>250-&lt;hostname&gt; Hello spammer.example [0:0:0:0:0:0:0:1])<br>250-PIPELINING<br>250-ENHANCEDSTATUSCODES<br>250-8BITMIME<br>250 STARTTLS<br>MAIL FROM:&lt;bad@user.com&gt;<br>250 2.1.0 Sender &lt;bad@user.com&gt; OK<br>RCPT TO:&lt;security@fivesec.de&gt;<br>250 2.1.5 Recipient &lt;security@fivesec.de&gt; OK<br>RCPT TO:&lt;anyone@gmail.com&gt;<br>250 2.1.5 Recipient &lt;anyone@gmail.com&gt; OK<br>DATA<br>354 Ok Send data ending with &lt;CRLF&gt;.&lt;CRLF&gt;<br>Subject: Test Stuff<br>Hello honeypot<br>.<br>250 Command accepted</pre><p>Look at the second recipient. anyone@gmail.com isn’t my domain, and the server said OK anyway. A real mail server that does that is an open relay, and it ends up on every blocklist on the internet within days. This one does it on purpose. It accepts everything, delivers nothing, and writes every byte to a structured log.</p><p>That’s the whole idea of the Fivesec SMTP Honeypot. Anyone who scans the internet for mail servers they can abuse, whether spam bots, relay testers or someone trying out a phishing campaign, finds a server that seems happy to help. In return, they leave behind their IP address, the hostname they claim to be, the envelope sender, every address they wanted to reach, and the full raw message. Nothing ever leaves the box.</p><p>Building it raised a question I hadn’t really thought about before: do you need a full mail server to pretend to be one? And if not, how little can you get away with?</p><p>The answer, as so often: build your own. With Apache James and Spring Boot that turned out to be surprisingly quick, <em>provided</em> you understand the one part of email that matters here: SMTP, the Simple Mail Transfer Protocol. A honeypot doesn’t need mailboxes, IMAP, spam filtering or retry queues. It only has to speak SMTP well enough that the other side keeps talking.</p><p>This article walks through how the honeypot works, what it records, the part that turned out to be more code than the protocol itself, and where it still gives itself away.</p><h3>Why SMTP makes a good honeypot</h3><p>SMTP is old, plain text, and unauthenticated by default on port 25. Any host on the internet can connect to any mail server and offer it a message. That’s how email works, and it’s also why mail servers are such an attractive target. An open relay, a server that forwards mail for anyone to anyone, is free sending capacity and a borrowed reputation.</p><p>That makes the attacker’s first move very predictable: connect, say EHLO, set some sender, and try a recipient on a domain the server has no business accepting. If the answer is 250, the relay is open.</p><p>A honeypot only has to win that one exchange. It doesn’t have to deliver mail, store it for anyone, or be a convincing mail server for long. It has to:</p><ul><li>speak SMTP correctly enough that clients don’t give up,</li><li>say yes where a real server would say no,</li><li>record everything, and</li><li>never, under any circumstances, actually forward a message.</li></ul><p>Points 1 and 2 are protocol work. Point 3 is a logging decision. Point 4 is the one that matters most, and as it turns out, it’s the easiest to guarantee.</p><h3>James, without the rest of James</h3><p>Apache James is best known as a complete Java mail server. What’s less well known is that its protocol implementations are published as standalone libraries. You can pull in just the SMTP state machine and a Netty transport, and leave the server itself, its mailbox storage and its configuration system behind.</p><p>That’s exactly what the honeypot does:</p><pre>implementation(&quot;org.apache.james:james-server-protocols-smtp:3.8.2&quot;)<br>implementation(&quot;org.apache.james.protocols:protocols-netty:3.8.2&quot;)<br>implementation(&quot;org.apache.james:metrics-logger:3.8.2&quot;)</pre><p>What you get from that is the part that’s tedious and easy to get wrong: command parsing, the session state machine (no ‘MAIL‘ before ‘EHLO‘, no ‘DATA‘ before ‘RCPT‘), the EHLO capability list, enhanced status codes, dot-unstuffing of the message body, the `Received:` header, and the STARTTLS upgrade. What you don’t get is any opinion about what happens to a message once it’s accepted. That part is yours, and James asks for it through hooks. For a honeypot, that’s exactly the split you want: James makes it look like a real server, and you decide what it really does.</p><h3>The entire honeypot logic is one hook</h3><p>James models every decision point of an SMTP session as a hook: ‘HeloHook‘, ‘MailHook‘, ‘RcptHook‘, ‘MessageHook‘, and so on. Each one returns a ‘HookResult‘ that tells the protocol layer how to answer the client. The honeypot implements exactly one of them:</p><pre>@Component<br>class SmtpComponent(private val smtpService: SmtpService) : MessageHook {<br><br>    override fun onMessage(session: SMTPSession?, envelope: MailEnvelope?): HookResult {<br>        LOG.atInfo()<br>            .setMessage(&quot;receive new message&quot;)<br>            .addKeyValue(&quot;sessionId&quot;, session?.sessionID)<br>            .log()<br><br>        return smtpService.processEmail(session, envelope)<br>    }<br>}</pre><p><em>onMessage</em> is called after the client has finished the ‘DATA’ phase, i.e. after the terminating ‘.’. At that point James has the full envelope: the sender from ‘MAIL FROM’, every recipient from `RCPT TO`, and the raw message stream.</p><p>The honeypot registers no ‘RcptHook’ that could object, and in practice that means every recipient gets a ‘250’. Nobody says no, so James says yes. For a honeypot that’s the point: you want to see what the sender would have done with an open relay.</p><p>The wiring between Spring and James is the one bit of glue I’m actually fond of:</p><pre>@Service<br>class SmtpServer(<br>    private val smtpConfiguration: SMTPConfigurationImpl,<br>    private val hooks: List&lt;Hook&gt;,<br>    private val smtpProperties: SmtpProperties,<br>) : ApplicationListener&lt;ApplicationReadyEvent&gt; {<br><br>    override fun onApplicationEvent(event: ApplicationReadyEvent) {<br>        val chain = SMTPProtocolHandlerChain(DefaultMetricFactory())<br>        chain.addAll(hooks)<br>        chain.wireExtensibleHandlers()<br><br>        val protocol = SMTPProtocol(chain, smtpConfiguration)<br>        val serverFactory = NettyServer.Factory().protocol(protocol)<br>        serverFactory.secure(Encryption.createStartTls(createSSLContext()))<br><br>        server = serverFactory.build()<br>        server?.setListenAddresses(InetSocketAddress(smtpProperties.bindAddress, smtpProperties.port))<br>        server?.setGracefulShutdown(true)<br>        server?.bind()<br>    }<br>}</pre><p>‘hooks: List&lt;Hook&gt;’ is Spring injecting every bean that implements James’ ‘Hook’ interface. ‘chain.addAll(hooks)’ hands them to the protocol handler chain, and ‘wireExtensibleHandlers()’ connects them to the commands they belong to. Today that list has exactly one element. But adding a ‘RcptHook’ that rejects certain domains, or a ‘HeloHook’ that logs the client’s claimed hostname, means writing one more ‘<a href="http://twitter.com/Component">@Component</a>’. No registration code, no changes to ‘SmtpServer’.</p><p>The server starts on ‘ApplicationReadyEvent’, after the Spring context is fully up, and unbinds in a ‘<a href="http://twitter.com/PreDestroy">@PreDestroy</a>’ method. That gives Netty a clean lifecycle inside a regular Spring Boot app.</p><p>There’s also a small amount of configuration that tightens protocol behavior:</p><pre>config.setHeloEhloEnforcement(true)<br>config.setUseAddressBracketsEnforcement(true)</pre><p>Both are visible on the wire. Skip the greeting and you get ‘503 5.5.0 Need HELO or EHLO before MAIL’. Send ‘MAIL FROM:a@b.c’ without angle brackets and you get ‘501 5.1.7 Syntax error in MAIL command’. That’s a trade-off for a honeypot. Being strict makes the server look more like a real MTA, but a careless script that fails here never reaches ‘DATA’, and its message never gets logged. Strictness buys realism and costs some catch.</p><h3><strong>What the honeypot catches</strong></h3><p>The ‘SmtpService’ does three things with an accepted message: it reads the raw bytes, parses them with Jakarta Mail, and logs everything as one structured event.</p><pre>val data = envelope.messageInputStream.readAllBytes()<br>val rawEmail = String(data, Charsets.UTF_8)<br>val message = MimeMessage(Session.getDefaultInstance(Properties()), ByteArrayInputStream(data))<br><br>LOG.atInfo()<br>    .setMessage(&quot;processing incoming email&quot;)<br>    .addKeyValue(&quot;sessionID&quot;, session?.sessionID)<br>    .addKeyValue(&quot;remoteAddress&quot;, session?.remoteAddress)<br>    .addKeyValue(&quot;username&quot;, session?.username)<br>    .addKeyValue(&quot;fromAddress&quot;, envelope.maybeSender.asString())<br>    .addKeyValue(&quot;rawEmail&quot;, rawEmail)<br>    .addKeyValue(&quot;content&quot;, message.content.toString())<br>    .addKeyValue(&quot;messageRecipients&quot;, envelope.recipients.map { it.asString() }.joinToString(&quot;,&quot;))<br>    .log()<br><br>return HookResult.OK</pre><p>With ‘logging.structured.format.console=logstash’ (Spring Boot 3.4’s built-in structured logging), that turns into a single JSON line on stdout. Here is the one produced by the session at the top of this article, trimmed a little:</p><pre>{<br>  &quot;message&quot;: &quot;processing incoming email&quot;,<br>  &quot;sessionID&quot;: &quot;dc1ee8d6&quot;,<br>  &quot;remoteAddress&quot;: &quot;localhost/[0:0:0:0:0:0:0:1]:57171&quot;,<br>  &quot;username&quot;: null,<br>  &quot;fromAddress&quot;: &quot;bad@user.com&quot;,<br>  &quot;rawEmail&quot;: &quot;Received: from localhost (EHLO spammer.example) ([0:0:0:0:0:0:0:1])\r\n          by &lt;hostname&gt; (JAMES SMTP Protocols Server) with ESMTP ID dc1ee8d6;\r\n ...\r\nSubject: Test Stuff\r\nFrom: bad@user.com\r\n\r\nHello honeypot\r\n&quot;,<br>  &quot;content&quot;: &quot;Hello honeypot\r\n&quot;,<br>  &quot;messageRecipients&quot;: &quot;security@fivesec.de,anyone@gmail.com&quot;<br>}</pre><p>That’s the whole storage design, and it’s a deliberate one. There’s no database and no mailbox, just stdout. Docker collects it, and any log pipeline or SIEM that understands Logstash JSON can index it. A honeypot is only as useful as the place its data ends up, and a JSON line is the format that place most likely already understands.</p><p>The ‘Received:’ header that James prepends records what the client claimed in ‘EHLO’ next to the address it actually connected from. For a honeypot, that’s often the most interesting line of the whole message.</p><p>Note the difference between the envelope and the headers, too. ‘fromAddress’ and ‘messageRecipients’ come from the SMTP envelope (‘MAIL FROM’ / ‘RCPT TO’), not from the ‘From:’ and ‘To:’ headers inside the message. Those two can disagree, and in spam and phishing they often do. Logging both the envelope and the untouched raw message keeps that evidence intact for whoever does the analysis later.</p><h3>Where the code actually went: TLS</h3><p>Why does a honeypot need TLS at all? Because practically every real mail server advertises ‘STARTTLS’ in its ‘EHLO’ response today, and one that doesn’t stands out. The surprise was the cost: if you count lines, the SMTP part of this project is tiny. The biggest single block of code is turning two PEM files into something Java will use for TLS.</p><p>The certificate and key live on the classpath as plain PEM files, which is what OpenSSL and pretty much every certificate tool produce. Java’s TLS stack wants a ‘KeyStore’. Getting from one to the other takes BouncyCastle and around 60 lines:</p><pre>val keyObject = PEMParser(InputStreamReader(keyResource.inputStream)).readObject()<br><br>val privateKey = when (keyObject) {<br>    is PEMKeyPair -&gt; keyConverter.getKeyPair(keyObject).private      // &quot;BEGIN RSA PRIVATE KEY&quot;<br>    is PrivateKeyInfo -&gt; keyConverter.getPrivateKey(keyObject)       // &quot;BEGIN PRIVATE KEY&quot; (PKCS#8)<br>    else -&gt; throw IllegalArgumentException(&quot;Unsupported key format: ${keyObject.javaClass}&quot;)<br>}<br><br>val keyStore = KeyStore.getInstance(&quot;PKCS12&quot;)<br>keyStore.load(null, null)<br>keyStore.setKeyEntry(&quot;fivesec-service-key&quot;, privateKey, smtpProperties.keyPassword?.toCharArray(), arrayOf(certificate))</pre><p>The ‘when’ branch is the kind of detail you only learn by having it fail. The same ‘openssl’ command can give you either of two private-key formats depending on version and flags, and BouncyCastle returns a different type for each. Handling both means you don’t have to remember which one your certificate tooling produced this time.</p><p>The resulting ‘SSLContext’ is handed to ‘Encryption.createStartTls(…)’, and the effect is visible in the protocol. Before the upgrade, the ‘EHLO’ response advertises ‘250 STARTTLS’. After ‘STARTTLS’ and the handshake (TLS 1.3 in my local test), the capability disappears from the list, because you can’t upgrade twice. Any client can test this with OpenSSL:</p><pre>openssl s_client -connect localhost:5587 -starttls smtp</pre><p>Two details are worth knowing. First, STARTTLS is offered, not required. Plaintext sessions are accepted just the same, which is right for a honeypot: you want to catch the clients that don’t bother with encryption too. And because TLS ends inside the application, the honeypot still logs the full plaintext of encrypted sessions. Second, the repo ships a self-signed test certificate for ‘localhost’. It’s fine for local testing, but for a public deployment you’d swap in a real one via ‘smtp.server.cert-name’ and ‘smtp.server.key-name’. Since they’re loaded from the classpath, they have to be on it, so mount them accordingly.</p><h3>Deploying it</h3><p>The ‘docker-compose.yaml’ is short and makes one opinionated move:</p><pre>ports:<br>  - 587:5587<br>  - 25:5587</pre><p>Both the classic MX port 25 and the submission port 587 lead to the same listener on 5587. The container never needs to bind a privileged port, and the honeypot sees traffic on both.</p><p>Mass scanners will find an open port 25 without any help. If you also want mail sent to a specific domain, add an MX record for that domain pointing at the host. And just like that, your honeypot is ready for traffic.</p><h3>Where the honeypot still gives itself away</h3><p>The easiest way to understand a honeypot is to ask two questions: can it hurt anyone, and what does it miss? Testing the running server against some edge cases turned up a few honest answers.</p><p>It never relays and never delivers. There’s no outbound SMTP client in the project at all. This is the single most important safety property of a honeypot that looks like an open relay, and it holds by construction: there’s no code path that could forward a message.</p><p>It doesn’t offer AUTH. ‘AUTH LOGIN’ gets ‘500 5.5.1 Command AUTH unrecognized’, so the ‘username’ field in the log is always ‘null’. Port 587 is where login attempts happen, so this is the biggest blind spot. Catching credential stuffing is the next hook to write, and it’s exactly the kind of thing the ‘List&lt;Hook&gt;’ wiring makes cheap.</p><p>There’s no size limit. I sent a 20 MB message. It was accepted, read into memory with ‘readAllBytes()’, and written out as a single log line of 20 million characters. A honeypot accepts anything from anyone by design, which makes this its easiest denial-of-service. It’s the first knob I’d turn: James’ ‘SMTPConfiguration’ interface has a ‘getMaxMessageSize()’, but there’s no setter on ‘SMTPConfigurationImpl’, so it stays at its default. Overriding it in the config bean is a one-liner that this project doesn’t have yet.</p><p>Parsing happens before logging, and that can lose evidence. I sent a message declaring ‘charset=no-such-charset’. Jakarta Mail threw ‘UnsupportedEncodingException’ while computing ‘message.content’, the service caught it and returned ‘HookResult.DENYSOFT’, and the client got ‘451 Temporary problem. Please try again later’. Responding with a temporary error is reasonable, since a real sender would retry. But because the exception happens while the log event is still being built, the raw email from that attempt is never logged. For a honeypot, malformed mail is the interesting mail. The fix is straightforward: log ‘rawEmail’ first, then try to parse.</p><p>Relatedly, ‘message.content.toString()’ is only useful for simple text messages. For a multipart message, which describes most real mail and almost all mail with attachments, the ‘content’ field just says ‘jakarta.mail.internet.MimeMultipart@78e3c8da’. The full message is still in ‘rawEmail’, so nothing is lost, but the convenience field quietly stops being convenient.</p><p>It announces what it is. The greeting says ‘JAMES SMTP Protocols Server’, and the hostname it reports is the machine’s hostname. There is an ‘smtp.server.hostname’ property, but nothing passes it to James yet. Anyone fingerprinting SMTP banners can tell this isn’t Postfix or Exchange. For catching opportunistic spam bots that probably doesn’t matter. For anything more targeted, it does.</p><p>A startup failure is quiet. ‘SmtpServer’ catches exceptions in ‘onApplicationEvent’ and logs them. If the certificate is missing, Spring Boot keeps running and Tomcat stays up, but nothing is listening on the SMTP port. A health check that actually connects to the SMTP port would catch that.</p><p>None of these are hard to fix. I’m listing them because they’re the real cost of building a honeypot yourself: every behavior a real mail server has and yours doesn’t is a way to spot it, and every input you accept is one you have to survive.</p><h3>The part worth taking away</h3><p>I expected an SMTP honeypot to be an infrastructure project: run Postfix, bend its configuration into an open relay, and hope you never get it wrong. What I ended up with is a Spring Boot service where the SMTP protocol is a library, the honeypot logic is one method, and the most complicated code is converting certificate formats.</p><p>The thing that makes it safe isn’t a setting, it’s an absence. A Postfix-based honeypot can’t relay because of configuration. This one can’t relay because there is no code that sends mail. That’s a stronger guarantee, and it generalizes: when you build something that is supposed to look dangerous, try to make the dangerous part impossible rather than merely disabled.</p><p>The other lesson is about what “saying yes” really costs. Saying yes to every recipient was one missing hook. Saying yes safely is where all the remaining work is: never relaying, bounding memory, logging before parsing, and not announcing what you are. If you’re thinking about running a honeypot of your own, those are the questions to start with, long before you worry about how convincing the banner looks.</p><p>The full source code is on GitHub: [fivesec-smtp-honeypot](<a href="https://github.com/fivesecde/fivesec-smtp-honeypot">https://github.com/fivesecde/fivesec-smtp-honeypot</a>).</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=42814bdf4935" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[What 10,000 RFCs Reveal About 58 Years of Internet History]]></title>
            <link>https://medium.com/@js_9757/what-10-000-rfcs-reveal-about-58-years-of-internet-history-3db9ecfd12ac?source=rss-1d907e2b272e------2</link>
            <guid isPermaLink="false">https://medium.com/p/3db9ecfd12ac</guid>
            <category><![CDATA[research]]></category>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[data-analysis]]></category>
            <dc:creator><![CDATA[Jens@Fivesec]]></dc:creator>
            <pubDate>Tue, 29 Sep 2026 19:19:10 GMT</pubDate>
            <atom:updated>2026-09-29T19:19:10.721Z</atom:updated>
            <content:encoded><![CDATA[<p><strong>An empirical analysis of the RFC database uncovers patterns of authorship concentration, geopolitical influence, and unexpected anomalies across five decades of internet standardization</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*aBFjVIHN_HUa6d6y" /><figcaption>Photo by <a href="https://unsplash.com/@vincentiu?utm_source=medium&amp;utm_medium=referral">Vincentiu Solomon</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>In the dusty corridors of internet history, there exists a document, thousands of them, really. The RFCs (Request for Comments) are the DNA of the modern internet. They define TCP/IP, HTTP, DNS, TLS, BGP, SSH. They are the invisible architecture upon which billions of people depend every day.</p><p>But who writes these documents? Where do they come from? How has the internet’s authorship landscape changed over 58 years?</p><p>I analyzed the complete RFC database (of course not by hand), 10,050 documents, 7,529 authors, spanning 1968 to 2026, and what I found may surprise you.</p><h3><strong>The Database: A 58-Year Archive</strong></h3><p>The RFC database is not just a technical archive: it is one of the most complete records of collaborative technical production ever assembled.</p><p>Some metrics for you</p><ul><li>Total RFCs <strong>10.050</strong></li><li>Time span <strong>February 1968 — September 2026</strong></li><li>Unique authors <strong>7.529</strong></li><li>Total author entries <strong>22,027</strong></li><li>RFCs with authors <strong>9.221 (91.8%)</strong></li><li>RFCs without authors <strong>829 (8.2%)</strong></li><li>Document relations (updates/obsoletes) <strong>7.408</strong></li></ul><p>That’s nearly six decades of human collaboration, codified in text.</p><p>But before I dive into the findings, I should mention a crucial caveat: <strong>This is observational data, not a controlled experiment.</strong> Correlation does not equal causation. What follows is a story the data tells, not a story the data proves.</p><h3><strong>Finding #1: The RFCs areRun by a Tiny Elite</strong></h3><p>If you think the internet is democratic, think again.</p><p>The authorship distribution in the RFC database is one of the most skewed that empirical research has ever documented. I calculated the <strong>Gini coefficien (</strong>measure of inequality ranging from 0 (perfect equality) to 1 (total inequality))and got a result of <strong>0.87</strong>.</p><p>For context: the global income Gini coefficient is typically 0.2–0.8. The RFC authorship is <em>more</em> concentrated than income inequality in the most unequal countries on Earth.</p><p><strong>The Lorenz Curve</strong></p><p>| Group | Share of authors | Share of authorships |</p><p>| Top 1% | 0.01 | ~12% |</p><p>| Top 5% | 0.05 | ~25% |</p><p>| Top 10% | 0.10 | ~30% |</p><p>| Bottom 90% | 0.90 | ~70% |</p><p>The top 10% of authors produce 30% of all RFCs. The top single author <strong>J. Postel, </strong>contributed 110 RFCs over 27 years, representing <strong>1.5% of all RFCs produced in 58 years.</strong></p><p><strong>The Hall of Fame (Top 10 by RFC count)</strong></p><ul><li>1, J. Postel | 110 | 1970–1997 (27 years)</li><li>2, Hannes Tschofenig | 95 | 2004–2026 (22 years)</li><li>3, Mohamed Boucadair | 91</li><li>4 , Adrian Farrel | 74 | 2003–2026 (23 years)</li><li>5 , R. Housley | 64 | 1993–2019 (26 years)</li><li>6, Keith McCloghrie | 63</li><li>7, Yakov Rekhter | 63 | 1990–2015 (25 years)</li><li>8, Gonzalo Camarillo | 61</li><li>9, Qin Wu | 58</li><li>10, Jari Arkko | 57 | 2002–2026 (24 years)</li></ul><p><strong>Interpretation:</strong>The internet is not built by committees of thousands. It is built by a small, highly productive core, a pattern consistent with what researchers call the “meritocratic hierarchy” of the IETF. Postel’s dominance is especially remarkable: he was arguably the original “RFC editor,” the person who assigned numbers and coordinated the entire series. His high count may partly reflect his editorial role rather than purely his writing.</p><h3><strong>Finding #2: The Year 2006 Breaks Everything</strong></h3><p>The most statistically anomalous year in 58 years of RFC history is <strong>2006</strong>, with <strong>459 RFCs published</strong>.</p><p>The long-term average is 165.9 RFCs per year. 2006 produced <strong>177% above the mean</strong>. The z-score is <strong>+2.49, </strong>the only year in the entire dataset exceeding |z| = 2.</p><pre><br>Year  RFCs    z-score    Context<br>-----+--------+----------+--------------------------------<br>1968    1      -1.40    First RFC ever<br>1971   182      +0.14    ARPANET takes off<br>1993   173      +0.06    Post-ARPANET, World Wide Web emerges<br>1999   256      +0.77    Dotcom boom<br>2000   278      +0.95    Year 2000 effects<br>2005   326      +1.36    Upward trajectory<br>2006   459      +2.49    HISTORICAL OUTLIER<br>2007   319      +1.30    Back to trend<br>2011   390      +1.91    Peak of the modern era<br>2023   173      +0.06    Returns to 1993 levels<br>ma</pre><p>What happend in 2006?</p><h3><strong>Finding #3: The Internet Has Grown Up (and Grown Old)</strong></h3><p>RFC production has gone through distinct phases:</p><pre>1960s:    2 RFCs     (0.0%)   — The experiment begins<br>1970s:  552 RFCs     (5.6%)   — ARPANET era<br>1980s:  316 RFCs     (3.2%)   — Contraction? Transition?<br>1990s: 1,028 RFCs    (10.5%)  — Internet explosion<br>2000s: 3,024 RFCs    (30.9%)  — Commercialization<br>2010s: 2,943 RFCs    (30.1%)  — Peak production<br>2020s: 1,331 RFCs    (13.6%)  — Mature / in progress</pre><p>The 2000s and 2010s together account for <strong>61% of all RFCs ever published</strong>.</p><p>After peaking in 2011 (390 RFCs), production has fallen to 173 RFCs in 2023, a <strong>56% decline from peak</strong>. Is this maturity? A data gap? Or a reflection that the hardest problems have already been solved?</p><p>T<strong>he Category Revolution</strong></p><p>Perhaps the most telling shift is in <em>what kind </em>of RFCs are produced.</p><pre>| Era | PROPOSED STANDARD | INFORMATIONAL | EXPERIMENTAL |<br>|-----|-------------------|---------------|--------------|<br>| 1980s | — | — | — |<br>| 1990s | 5 | 21 | 16 |<br>| 2000s | 125 | 117 | 16 |<br>| 2010s | 195 | 125 | 29 |<br>| 2020s | 122 | 57 | 9 |</pre><p>In the 1990s, <strong>INFORMATIONAL</strong> RFCs were most common (21 vs. 5 PROPOSED STANDARD). By the 2010s, <strong>PROPOSED STANDARD </strong>dominates (195 vs. 125). Today, it accounts for 44% of all RFCs.</p><p><strong>Interpretation:</strong> The IETF has professionalized. RFCs are no longer experimental notes or informational documents. They are serious, standards-track engineering.</p><h3><strong>Finding #4: The IETF Is American, by a Large Margin</strong></h3><p>Geopolitically, the RFC database tells a story of American dominance.</p><p><strong>Authors by Country</strong></p><pre>| Country | Author Entries | Unique Authors | Share |<br>|---|---|---|---|<br>| United States | 972 | 467 | 42.1% |<br>| China | 226 | 117 | 9.8% |<br>| Germany | 179 | 81 | 7.8% |<br>| France | 169 | 67 | 7.3% |<br>| United Kingdom | 115 | 58 | 5.0% |<br>| India | 101 | 31 | 4.4% |<br>| Canada | 99 | 38 | 4.3% |<br>| Sweden | 78 | 37 | 3.4% |<br>| Spain | 73 | 33 | 3.2% |<br>| Finland | 57 | 22 | 2.5% |</pre><p><strong>Authors Per Decade (How the pool grew)</strong></p><pre>| Decade | Unique Authors |<br>|---|---|<br>| 1960s | 13 |<br>| 1970s | 270 |<br>| 1980s | 172 |<br>| 1990s | 1,366 |<br>| 2000s | 2,948 |<br>| 2010s | 2,932 |<br>| 2020s | 1,682 |</pre><p>The author pool exploded in the 1990s and 2000s, then plateaued. The 2020s are still in progress, but the rate of new author entry appears to be slowing.</p><h3><strong>Finding #5: Corporate Dominance by Cisco, Huawei, Ericsson</strong></h3><p>If the IETF is a meritocracy, it is a meritocracy sponsored by corporations.</p><p><strong>Top 10 Organizations by Author Entries</strong></p><pre>| Rank | Organization | Entries | RFCs | Authors |<br>|---|---|---|---|---|<br>| 1 | Cisco Systems, Inc. | 2,493 | 1,661 | 664 |<br>| 2 | Huawei Technologies | 644 | 485 | 165 |<br>| 3 | Ericsson | 555 | 421 | 128 |<br>| 4 | Juniper Networks | 520 | 395 | 153 |<br>| 5 | Google | 322 | 258 | 150 |<br>| 6 | Nokia | 273 | 226 | 98 |<br>| 7 | ISI | 182 | 135 | 29 |<br>| 8 | Microsoft | 157 | 141 | 64 |<br>| 9 | Microsoft Corporation | 152 | 114 | 49 |<br>| 10 | Sun Microsystems | 148 | 123 | 80 |</pre><p>Cisco alone accounts for <strong>11% of all author entries,</strong> nearly four times the second-place company (Huawei). The top three (Cisco, Huawei, Ericsson) produce more than all of the remaining 3,700+ organizations combined.</p><p><strong>Interpretation:</strong> The IETF’s “open process” is funded largely by corporate R&amp;D budgets. This is not inherently problematic, but it raises questions about whose interests shape the standards.</p><h3><strong>Finding #6: DNS Is the Most Important Protocol</strong></h3><p>RFC 1035 (Domain names implementation and specification) has been updated <strong>29 times</strong> by other RFCs. It is the most “updated-by” referenced document in the entire database.</p><p>RFC 1034 (the conceptual companion) has 19 updates. Together, the DNS pair has been modified by 48 different RFCs.</p><p><strong>Most Referenced RFCs (by updates)</strong></p><pre>| RFC | Updates | Title |<br>|---|---|---|<br>| 1035 | 29 | Domain names — implementation |<br>| 3261 | 21 | SIP: Session Initiation Protocol |<br>| 1034 | 19 | Domain names — concepts |<br>| 2026 | 15 | The Internet Standards Process |<br>| 3473 | 14 | Generalized MPLS Signaling |</pre><p><strong>Why?</strong> DNS is the “phonebook of the internet.” Every time a new requirement emerges (DNSSEC, IPv6, DNS-over-HTTPS), someone has to update DNS. It is the protocol that cannot stop evolving. But hey, just a guess!</p><h3><strong>Most Obsoleting RFCs</strong></h3><pre>| RFC | Obsoletes | Title |<br>|---|---|---|<br>| 4510 | 10 | LDAP Technical Specification |<br>| 4033 | 9 | DNS Security Introduction |<br>| 4034 | 9 | Resource Records for DNS Security |<br>| 4035 | 9 | Protocol Modifications for DNS Security |<br>| 7805 | 9 | Moving Outdated TCP Extensions |</pre><h3><strong>Finding #7: Author Count and Document Length Are Almost Uncorrelated</strong></h3><p>Intuitively, you might expect that more authors mean longer documents. The data says: not really.</p><p><strong>Pearson r = 0.179</strong> (N = 9,837). The R-squared is 3.2%. Only 3% of the variance in page count is explained by author count.</p><p><strong>Interpretation:</strong> The length of an RFC is determined by the <strong>complexity of the protocol</strong>, not the number of people writing about it. Nine authors do not automatically produce a 9x longer document.</p><h3>F<strong>inding #8: The Longest Careers in Internet History</strong></h3><p>Fifteen authors have contributed RFCs over 20 or more years:</p><pre>| Author | RFCs | Span | Years |<br>|---|---|---|---|<br>| Fred Baker | 48 | 1991–2020 | 29 years |<br>| Jon Postel | 50 | 1970–1998 | 28 years |<br>| Lou Berger | 43 | 1998–2026 | 28 years |<br>| J. Postel | 110 | 1970–1997 | 27 years |<br>| Dan Wing | 40 | 1998–2025 | 27 years |<br>| George Swallow | 38 | 1997–2024 | 27 years |</pre><p><strong>Fred Baker</strong> holds the record for longest continuous involvement: 48 RFCs over 29 years, from 1991 to 2020. That’s nearly three decades of shaping the internet.</p><h3><strong>Finding #9: The Hidden Democratic Trend</strong></h3><p>Here is something unexpected. The top authors per decade have <em>decreased</em> in productivity:</p><pre>| Era | Top Author | RFCs in that decade |<br>|---|---|---|<br>| 1970s | S. Crocker | 15 |<br>| 1980s | J. Postel | 10 |<br>| 1990s | Craig Partridge | 3 |<br>| 2000s | Keith McCloghrie | 6 |<br>| 2010s | Hannes Tschofenig | 15 |<br>| 2020s | Michael B. Jones | 8 |</pre><p>The 2020s top author (Michael B. Jones, 8 RFCs) has produced fewer RFCs than the 2010s top author (Tschofenig, 15). The 1990s top was just 3.</p><p><strong>Hypothesis:</strong> The IETF may be democratizing. Contributions are becoming more distributed, less dependent on heroic single authors. This could reflect the increasing scale and formality of the standards process.</p><p><strong>This is a hypothesis, not a proven fact!!</strong> More data is needed!!</p><h3><strong>Finding #10: The Most Prolific Collaborations</strong></h3><p>Internet standards are rarely written alone. Here are the strongest collaboration pairs (≥3 shared RFCs):</p><pre>| Rank | Author 1 | Author 2 | Shared RFCs |<br>|---|---|---|---|<br>| 1 | Ali Sajassi | Jorge Rabadan | 15 |<br>| 2 | Mohamed Boucadair | Tirumaleswar Reddy.K | 15 |<br>| 3 | Clarence Filsfils | Stefano Previdi | 13 |<br>| 4 | Keith McCloghrie | Marshall T. Rose | 13 |<br>| 5 | Clarence Filsfils | Daniel Voyer | 11 |</pre><h3><strong>The Keyword Landscape: What the Internet Cares About</strong></h3><p>Across 9,842 RFCs with keywords, the most common topics are:</p><pre>| Keyword | Count | Keyword | Count |<br>|---|---|---|---|<br>| ftp | 17 | dns | 8 |<br>| multicast | 12 | security | 5 |<br>| bgp | 9 | sip | 6 |<br>| mail | 9 | mib | 7 |</pre><p>(Most keywords are multi-word phrases; single-word counts are shown above.)</p><p>The dominant theme is clear: <strong>TCP/IP-based networking</strong> occupies the center of gravity. Security is present but not dominant. Mobile and wireless are emerging but not yet central.</p><h3><strong>Anomaly 1: The 1980s Contraction</strong></h3><p>RFC production dropped from 552 in the 1970s to 316 in the 1980s, a <strong>43% decline</strong>. This was a period of intense debate over network architecture (TCP/IP vs. OSI). The drop may reflect uncertainty and fragmentation in the standards community.</p><h3><strong>Anomaly 2: The Longest RFC</strong></h3><p><strong>RFC 5661</strong> (2010) is <strong>617 pages long</strong> , the Network File System (NFS) Version 4 Minor Version 1 Protocol specification. The second longest is RFC 8881 (560 pages, the same protocol, reissued). The third is RFC 1142 (517 pages, an OSI routing protocol from 1990).</p><p><strong>Observation:</strong> The longest RFCs are either complex, fully specified protocols (NFS) or comprehensive reference documents (OSI IS-IS, Internet Security Glossary). They are not protocol designs but <em>specifications</em>.</p><h3><strong>Anomaly 3: The “Legacy” Stream Disappeared</strong></h3><p>In the 1970s, all RFCs were “legacy” (a historical classification for pre-IETF documents). Today, the legacy stream is gone and “ietf” accounts for 85% of all streams. This transition from legacy to ietf marks the professionalization of the IETF.</p><h3><strong>Limitations and Caveats</strong></h3><p>Before you draw conclusions, consider:</p><ul><li><strong>Survivorship bias: </strong>Only published RFCs are in the database. Drafts that never became RFCs are invisible.</li><li><strong>Missing data: </strong>215 RFCs are 404 (not found). 264 have no date. 915 have no abstract. 7.419 have no errata URL.</li><li><strong>Measurement bias: </strong>Author attribution depends on the availability of XML or HTML source documents. Older RFCs may have incomplete author data.</li><li><strong>No causal inference: </strong>Correlation is not causation. Any interpretation is speculative without additional evidence.</li><li><strong>Multiple testing: </strong>With thousands of comparisons, some anomalies may be statistical noise rather than real effects.</li></ul><p><strong>What This Means</strong></p><p>The RFC database tells a coherent story:</p><ul><li><strong>The internet began as a small, American, ARPANET-era project</strong> with a handful of authors.</li><li><strong>It exploded in the 1990s and 2000s</strong> as the commercial internet took off, peaking around 2011.</li><li><strong>It is now dominated by a small elite</strong> (Gini = 0.87) and a handful of corporations (Cisco leads).</li><li><strong>It has professionalized: </strong>PROPOSED STANDARD RFCs dominate. The stream is ietf, not legacy.</li><li><strong>It may be democratizing:</strong> Top-author productivity is declining in recent years.</li><li><strong>It is maturing:</strong> Production has fallen 56% from its 2011 peak. The hardest problems may already be solved.</li></ul><h3><strong>Acknowledgments</strong></h3><p>This analysis would not have been possible without the IETF’s commitment to open documentation. Every RFC is a gift to humanity. Every author who wrote, reviewed, or maintained one deserves recognition, even if the data shows that a small number of them did the bulk of the work.</p><p><strong>Further Reading</strong></p><ul><li>IETF Official Website: <a href="https://www.ietf.org/">https://www.ietf.org</a></li><li>RFC Editor: <a href="https://www.rfc-editor.org/">https://www.rfc-editor.org</a></li><li>“The Magic Cauldron” — Douglas Engelbart’s 1962 NLS proposal (the intellectual ancestor of the RFC process)</li><li>“How to Choose an Internet Standard” — Rough Consensus and Running Code</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3db9ecfd12ac" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[I Finally Understood Distributed Tracing After Thinking About One HTTP Request]]></title>
            <link>https://medium.com/@js_9757/i-finally-understood-distributed-tracing-after-thinking-about-one-http-request-111b7e767491?source=rss-1d907e2b272e------2</link>
            <guid isPermaLink="false">https://medium.com/p/111b7e767491</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[cybersecurity]]></category>
            <category><![CDATA[observability]]></category>
            <dc:creator><![CDATA[Jens@Fivesec]]></dc:creator>
            <pubDate>Fri, 03 Jul 2026 07:05:38 GMT</pubDate>
            <atom:updated>2026-07-03T07:05:38.973Z</atom:updated>
            <content:encoded><![CDATA[<p>Logs tell you <strong>what</strong> happened. Metrics tell you <strong>how often</strong> it happened. Distributed traces tell you <strong>why</strong> it happened.</p><p>If you’ve ever tried debugging a microservice application in production, you’ve probably experienced this.</p><p>A user reports that an API request took five seconds. Your dashboards show that CPU usage is normal. Memory looks fine. No alerts fired.</p><p>The logs? Thousands of lines spread across six different services.</p><p>Welcome to distributed systems.</p><p>At some point I realized that logs and metrics simply answer different questions than the one I was asking.</p><p>I didn’t want to know <em>whether</em> my services were healthy.</p><p>I wanted to know:</p><p><strong><em>What exactly happened to this one request?</em></strong></p><p>That’s precisely the problem distributed tracing was designed to solve.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*3wCYICI-uCHswHGQ" /><figcaption>Photo by <a href="https://unsplash.com/@pixtresa?utm_source=medium&amp;utm_medium=referral">Pix Tresa</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><h3>Why Logs Aren’t Enough</h3><p>Imagine a simple request entering an API Gateway.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/710/1*FI3sLgLsSBenkQH2ETMSQw.png" /></figure><p>From the user’s perspective, this is one request.</p><p>From your infrastructure’s perspective, it’s dozens of network calls, database queries, cache lookups, and asynchronous operations.</p><p>Every service writes its own logs. Every service exports its own metrics. None of them automatically belong together.</p><p>Debugging suddenly becomes a treasure hunt:</p><ul><li>Search Gateway logs</li><li>Find a timestamp</li><li>Search User Service logs</li><li>Guess which request belongs together</li><li>Repeat for every downstream service</li></ul><p>It works…</p><p>…until production traffic reaches a few thousand requests per second.</p><h3>The Missing Piece: A Shared Identity</h3><p>Distributed tracing introduces one simple but incredibly powerful idea:</p><p><strong><em>Every request receives a globally unique identifier that follows it everywhere.</em></strong></p><p>Instead of independent log entries, every service contributes to the same story. That story is called a <strong>trace</strong>.</p><h3>Trace vs Span</h3><p>These two terms confuse almost everyone at first. They’re actually simple.</p><p>A <strong>trace</strong> represents the complete lifecycle of a request.</p><p>A <strong>span</strong> represents a single operation inside that lifecycle.</p><p>Think of a trace as an entire road trip. Each span is one individual leg of the journey.</p><pre>Trace<br>│<br>├── Gateway receives request<br>│<br>├── User Service HTTP call<br>│<br>├── Database query<br>│<br>├── Payment Service HTTP call<br>│<br>└── Notification Service publishes message</pre><p>Every span records information such as:</p><ul><li>start time</li><li>duration</li><li>status (success or error)</li><li>operation name</li><li>metadata (HTTP method, SQL statement, response code…)</li><li>parent span</li></ul><p>The parent-child relationship allows tracing systems to reconstruct the complete execution tree.</p><h3>The Trace ID Never Changes</h3><p>This is the concept that made everything click for me. During an entire request lifecycle:</p><ul><li>the <strong>Trace ID</strong> stays exactly the same</li><li>the <strong>Span ID</strong> changes at every operation</li></ul><p>For example:</p><pre>Gateway<br>Trace ID: 4bf92f3577b34da6...<br>Span ID: a1</pre><p>Gateway calls User Service.</p><pre>User Service<br>Trace ID: 4bf92f3577b34da6...<br>Span ID: b7<br>Parent: a1</pre><p>User Service calls PostgreSQL.</p><pre>Database<br>Trace ID: 4bf92f3577b34da6...<br>Span ID: c4<br>Parent: b7</pre><p>Notice how only the Span ID changes. The Trace ID remains constant throughout the entire request.</p><p>That’s what allows tracing backends to reconstruct the complete call chain automatically.</p><h3>How Does Another Service Know the Trace ID?</h3><p>This is where context propagation comes in. Every outgoing request carries tracing information.</p><p>Today almost every modern tracing implementation uses the <a href="https://www.w3.org/TR/trace-context/"><strong>W3C Trace Context</strong></a> standard.</p><p>The context is stored inside a simple HTTP header:</p><pre>traceparent:<br>00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01</pre><p>It consists of four fields:</p><ul><li>Version: Trace Context version</li><li>Trace ID: Identifies the complete request</li><li>Parent ID: Span that initiated the call</li><li>Trace Flags: Sampling information</li></ul><p>When Service A calls Service B:</p><ol><li>Service A inserts the traceparent header.</li><li>Service B reads it.</li><li>Service B creates a new span.</li><li>That new span becomes the parent for the next downstream call.</li></ol><p>No custom protocol. No vendor-specific implementation. Just one standardized header.</p><h3>One Missing Header Can Break Everything</h3><p>One thing that’s surprisingly easy to overlook:</p><p>Reverse proxies, API gateways, service meshes, and load balancers sometimes remove headers they don’t recognize.</p><p>If traceparent disappears at any point, the trace is silently split into two completely independent traces.</p><p>Everything still works. Nothing crashes.</p><p>Your tracing simply loses continuity.</p><p>Whenever introducing a new proxy, always verify that trace headers are forwarded unchanged.</p><p>It’s one of those tiny configuration mistakes that can cost hours of debugging later.</p><h3>Sampling: Because Recording Everything Doesn’t Scale</h3><p>In an ideal world, we’d record every request.</p><p>Reality is different. Large systems may generate millions of spans every minute.</p><p>Storage becomes expensive very quickly.</p><p>That’s why tracing systems use sampling.</p><h3>Head-Based Sampling</h3><p>The decision is made immediately.</p><pre>Start Request<br>       │<br>       ▼<br>Record?<br>   Yes / No</pre><p>If the trace is sampled, every downstream service records it.</p><p>If not, nobody records it. This approach is extremely efficient.</p><p>A common configuration might keep only 10% of requests.</p><h3>Tail-Based Sampling</h3><p>Tail sampling waits until the trace finishes.</p><p>Then it asks questions like:</p><ul><li>Did the request fail?</li><li>Did it take longer than one second?</li><li>Did it hit a specific service?</li></ul><p>Only then does it decide whether to keep the trace.</p><p>This produces much more valuable datasets but requires buffering spans until the entire request completes.</p><h3>OpenTelemetry Changed Everything</h3><p>For years every vendor had its own tracing SDK.</p><p>Switching observability platforms often meant rewriting instrumentation.</p><p><a href="https://opentelemetry.io/">OpenTelemetry</a> solved this problem.</p><p>It’s now the CNCF standard for collecting:</p><ul><li>traces</li><li>metrics</li><li>logs</li></ul><p>Most importantly, it speaks the W3C Trace Context standard by default.</p><p>That means services instrumented with different vendors can still participate in the same trace.</p><h3>Auto-Instrumentation Is Surprisingly Good</h3><p>One thing I underestimated was OpenTelemetry’s auto-instrumentation.</p><p>Instead of modifying application code everywhere, an instrumentation library hooks into common frameworks automatically.</p><p><em>HTTP clients. HTTP servers. Database drivers. Messaging libraries.</em></p><p>They all begin creating spans without changing business logic.</p><p>For many applications, that’s enough to gain immediate visibility.</p><p>Manual instrumentation can then be added only where business-specific spans make sense.</p><h3>The Only Configuration You Usually Need</h3><p>Most services can start exporting traces with just a few environment variables.</p><p>OTEL_SERVICE_NAMELogical service name</p><p>OTEL_EXPORTER_OTLP_ENDPOINTOpenTelemetry Collector endpoint</p><p>OTEL_TRACES_SAMPLERSampling strategy</p><p>OTEL_TRACES_SAMPLER_ARGSampling configuration</p><p>OTEL_PROPAGATORSContext propagation format</p><p>Typically, services send spans to an OpenTelemetry Collector using OTLP.</p><p>The collector batches, filters, and forwards data to backends like Grafana Tempo, Zipkin, or other observability platforms.</p><p>This separation is useful because changing your backend no longer requires touching application code.</p><p>How it may look in Grafana:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QxMTdlnCPKM3NAUgpVuyhQ.png" /></figure><h3>A Python FastAPI Example</h3><p>Getting started is refreshingly simple.</p><p>Install the OpenTelemetry packages alongside FastAPI and HTTPX.</p><p>Then, instead of launching Uvicorn directly, start it through the instrumentation wrapper:</p><pre>opentelemetry-instrument uvicorn app:app --host 0.0.0.0 --port 8000</pre><p>The instrumentation automatically creates spans for incoming HTTP requests, outgoing HTTPX calls, and propagates the traceparent header without modifying your routing logic.</p><p>Within minutes you’ll have an end-to-end trace showing exactly how a request moved through your services.</p><h3>Final Thoughts</h3><p>Distributed tracing isn’t about collecting more telemetry.</p><p>It’s about connecting the telemetry you already have.</p><p><strong>Logs remain essential. Metrics remain essential.</strong></p><p>But once requests cross service boundaries, neither tells the complete story.</p><p>Distributed tracing fills that gap by following a request from beginning to end, preserving context across every hop.</p><p>And thanks to OpenTelemetry and the W3C Trace Context standard, getting started is no longer a massive engineering project.</p><p>It’s often just a few environment variables away.</p><p>If you’re building microservices and still debugging production issues by manually correlating timestamps across log files, distributed tracing is probably the next capability your platform is missing.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=111b7e767491" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[From Patterns to Production: Lessons in Realistic Software Architecture]]></title>
            <link>https://medium.com/@js_9757/from-patterns-to-production-lessons-in-realistic-software-architecture-c11e8cd3adc4?source=rss-1d907e2b272e------2</link>
            <guid isPermaLink="false">https://medium.com/p/c11e8cd3adc4</guid>
            <category><![CDATA[platform-engineering]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[cloud-computing]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Jens@Fivesec]]></dc:creator>
            <pubDate>Mon, 02 Feb 2026 10:34:38 GMT</pubDate>
            <atom:updated>2026-02-02T10:34:38.979Z</atom:updated>
            <content:encoded><![CDATA[<p>Designing systems on paper is easy. Patterns look clean, diagrams are tidy, and everything seems under control. The real challenge begins when those decisions meet production: code behaves differently, teams face unexpected complexity, and small abstractions can explode into real problems.</p><p>Good architecture isn’t just about patterns or diagrams; it’s about understanding the trade-offs, communicating clearly with stakeholders, and taking responsibility for the consequences that ripple through your system.</p><p>What actually defines good software architecture? And must a software architect be able to code?</p><p>These are significant, often controversial questions. As always, the answer is probably “it depends”. But it’s precisely this “depends” that’s fascinating. It determines whether architecture delivers genuine value or merely produces attractive diagrams.</p><p>This article doesn’t aim to establish dogma but rather to take a realistic look at software architecture. From my perspective, architecture is less a document or set of diagrams and more a decision-making framework under uncertainty. These decisions always have consequences, technical, organisational, and commercial.</p><p>To establish common ground, let’s work through a concrete scenario.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*RGfEjBoNm8FT1pNk" /><figcaption>Photo by <a href="https://unsplash.com/@eilisgarvey?utm_source=medium&amp;utm_medium=referral">Eilis Garvey</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><h3>Context</h3><p>When dealing with abstract questions, each of us carries our own experiences, projects, and systems. Correspondingly, the mental images we conjure when discussing “architecture” vary considerably.</p><p>To align our thinking, let’s define a rough framework, not as absolute truth but as common ground for discussion.</p><h3>Background</h3><p>You’re working as a software architect at Grid-Cloud, a fictitious company. The objective is nothing less than building a European sovereign cloud platform, colloquially speaking: <em>“Build us our own AWS.”</em></p><p>The overall project comprises approximately 200 people.</p><p>Of these, roughly 25 work in software engineering, divided into verticals such as Compute, Storage, Network, and Core Services. The architecture team consists of 10 architects, split evenly between software and hardware/network specialists.</p><p>The pressure is immense: ambitious deadlines, high costs (the majority of staff are external specialists), and numerous known unknowns exist regarding platform design.</p><p>Our task as architects is to mediate between management (<em>northbound stakeholders</em>) and engineering (<em>southbound stakeholders</em>), whilst defining a clear cut-off point:</p><p>What constitutes a strategic architectural decision, and where is the clear boundary regarding engineering teams’ responsibility?</p><p>It’s precisely in this tension that what good architecture must deliver, and what it decidedly must not, becomes apparent.</p><h3>Why Do We Actually Need (Good) Software Architecture?</h3><p>At its core, software architecture is about deliberate boundaries within a clearly defined context. Architecture doesn’t describe every detail but establishes guardrails: Which problems do we solve? Which do we consciously not solve? And under what constraints do we make these decisions?</p><p>This sounds abstract, and it is. There’s no universal formula for good architecture. Every system, environment, and team brings its own challenges and potential.</p><p>Nevertheless, there’s a common denominator: architecture emerges where functional requirements, clear deliverables, and product specifics meet explicit quality attributes.</p><p>Typically, questions arise (a small sample) such as:</p><ul><li>How scalable must the system be?</li><li>What does scalability actually mean in a specific context? What are the consequences?</li><li>What level of latency is acceptable?</li><li>What happens in failure scenarios?</li><li>What constitutes a failure? Are there different types of failure?</li></ul><p>Good architecture means making these questions visible, transparent, and deciding them consciously (or consciously deferring them), rather than allowing solutions to emerge randomly in code.</p><h3>Can We Measure Architectural Quality?</h3><p>This raises the question: are there concrete, measurable metrics (KPIs) for software architecture? What might these be? Number of diagrams or word count in a document? Which tool (Confluence, Notion, etc.) the architectural specification was written in? How many user stories could be derived? Doesn’t sound particularly meaningful, does it?</p><p>Let’s try relative KPIs instead, asking ourselves:</p><ul><li>Is the problem clearly described and bounded?</li><li>Is the context clear and comprehensible?</li><li>For whom are we specifying, designing, and documenting software architecture?</li><li>Have we thought of everything? What have we overlooked?</li><li>Is everything clearly and comprehensibly described and sketched?</li><li>Is a coherent thread recognisable and traceable for all relevant stakeholders?</li><li>Is the architectural specification synchronised with the current development state or software releases, or are there clear, undocumented discrepancies?</li></ul><p>How do we measure and evaluate these metrics? The answer may be shockingly simple: communication. Communication with all relevant parties, actively seeking feedback, occasionally setting topics and texts aside briefly, and continually questioning ourselves. Discussing matters robustly but always fairly and objectively on a personal level. Architecture isn’t a one-time effort but an iterative learning process. Things get discarded, reconceived, and adjusted again. This isn’t failure but a sign of functioning architectural work.</p><h3>Must a Software Architect Be Able to Code?</h3><p>Perhaps the real question isn’t whether, but in what context.</p><p>Should an architect fundamentally understand how software is created?Should they have once worked as a developer? Or should they actively participate in implementation as part of the team?</p><p>In my personal opinion, I tend towards the following generalisation:</p><p><strong>Yes</strong>, a software architect should have solid programming knowledge and experience.</p><p><strong>No</strong>, a software architect should not be part of the development team writing code. Exceptions naturally prove the rule, but this should remain a rare exception and be clearly agreed upon. Ultimately, the answer remains a clear no.</p><p><strong>Why this “yes” is so important:</strong></p><p>Architectural decisions never remain at the diagram level. They always materialise in code, tests, deployments, monitoring, and operational running. Those who cannot assess the consequences of these decisions on implementation effort, complexity, and debugging risk designing systems that appear elegant on paper but are barely manageable in reality.</p><p>This is precisely where it gets interesting. Let’s examine a concrete example.</p><p>We’re to create a system consisting fundamentally of three microservices communicating via events, asynchronously. Only one service is accessible to the integrator and orchestrates all operations affecting the entire system.</p><p>Specifically, it’s about provisioning a cloud resource, in this case, a virtual machine.</p><p>The rough structure is quickly sketched: three services, clearly separated responsibilities, loosely coupled via events. At the architectural level, this sounds clean, modern, and scalable.</p><p>But this is precisely where architecture’s actual work begins.</p><p>Our task as software architects is now to describe this system not just roughly but precisely:</p><ul><li>What domain and technical problems arise from distribution?</li><li>Where are consistency boundaries?</li><li>What happens with partial failures?</li><li>What guarantees can the system provide, and which consciously not?</li></ul><p>As soon as we take the terms orchestration and asynchronous communication seriously, we quickly arrive at a familiar solution pattern: the Saga pattern for distributed transactions.</p><p><em>A transaction represents a unit of work, which can include multiple operations. Within a transaction, an event refers to a state change that affects an entity. A command encapsulates all information needed to perform an action or trigger a subsequent event.</em></p><p><em>Transactions must adhere to the principles of atomicity, consistency, isolation, and durability (ACID).</em></p><ul><li><strong><em>Atomicity: </em></strong><em>All operations succeed or no operations succeed.</em></li><li><strong><em>Consistency: </em></strong><em>Data transitions from one valid state to another valid state.</em></li><li><strong><em>Isolation: </em></strong><em>Concurrent transactions yield the same results as sequential transactions.</em></li><li><strong><em>Durability: </em></strong><em>Changes persist after they’re committed, even when failures occur.</em></li></ul><p><em>In a single service, transactions follow ACID principles because they operate within a single database. However, achieving ACID compliance across multiple services is more complex.</em></p><p>A domain operation say, “Create a VM”, suddenly no longer consists of a single database commit but a chain of distributed steps:</p><ul><li>Reserve network resources</li><li>Provision storage</li><li>Create compute instance</li><li>Update system state</li><li>Notify integrator</li></ul><p>Each of these steps occurs in a different service, with its own database, runtime, and error handling.</p><p>Classic ACID transactions no longer work system-wide. So we define a saga: a sequence of local transactions with associated compensating actions if a later step fails. At the architectural level, this is a sound decision.</p><p>But what does this actually mean for the software engineering team? What impact does this decision have on code complexity (clean code), time, testing, quality, and stability? Is this still the software architect’s responsibility or the engineering team’s?</p><h3>Engineering Interference</h3><p>From my perspective, two holistic worlds merge here: the tower of excellence and engineering reality.</p><p>Abstractly, on paper or in a specification, the problem seems solved. The architecture stands, the pattern is chosen, the diagrams are clean. The temptation is great to communicate externally: <em>“We’re finished.”</em></p><p>And from a certain perspective, that’s even true. But where’s the concrete implementation?</p><p>What signal does this send, especially to our northbound stakeholders? Doesn’t this quickly create the impression that the system now merely needs to be “built”?</p><p>This is an excellent situation for crashing a project!</p><p>In truth, frequently underestimated implementation complexity is tacitly offloaded onto the engineering team at this point. Under time pressure, this almost inevitably leads to things being “knocked out” not from incompetence but from structural pressure.</p><p>“Of course bad code can be cleaned up. But it’s very expensive.”</p><p><em>— Robert C. Martin</em></p><p>A programming-experienced architect, however, knows precisely what effects their decisions have on the real system. Architecture doesn’t end with boxes and arrows, it always materialises in code that must run, scale, be maintained, and analysed under real conditions.</p><p>Ultimately, we’re always discussing software delivered in a concrete form. However, how closely this implementation actually corresponds to the original specification is quite another matter.</p><p>Precisely here, proper bilateral stakeholder management becomes crucial.</p><p>Upwards, transparent communication about effort, risks, and technical consequences is essential. Downwards, clarity is needed about why certain complexity was consciously accepted.</p><p>Only when expectations are realistically set on both sides can architecture fulfil its actual role: not merely designing solutions but taking responsibility for their implementability.</p><p>“The only way to go fast, is to go well.”</p><p><em>— Robert C. Martin</em></p><h3>Conclusion</h3><p>Ultimately, it’s a combination of communication skills, abstraction capability, stakeholder management, experience and yes, programming experience that forms the foundation for playing a genuine key role in the holistic success of complex projects and product development as a software architect.</p><p>This includes continually questioning oneself and allowing oneself to be questioned. Architecture isn’t a status but a continuous learning process. Therein lies growth, both professionally and personally.</p><p>And yes: a software architect should know what they’re talking about. Because ultimately, it’s not the prettiest diagram that prevails but the reality in code.</p><p>And this reality will sooner or later tear down any tower of excellence if it’s not built on solid understanding of implementation.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c11e8cd3adc4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Stop Leaking Your Secrets: Solving the Hidden API Key/Secret Problem in Web Apps]]></title>
            <link>https://medium.com/@js_9757/stop-leaking-your-secrets-solving-the-hidden-api-key-secret-problem-in-web-apps-5b88bc1347ed?source=rss-1d907e2b272e------2</link>
            <guid isPermaLink="false">https://medium.com/p/5b88bc1347ed</guid>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[angular]]></category>
            <category><![CDATA[cybersecurity]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Jens@Fivesec]]></dc:creator>
            <pubDate>Wed, 05 Nov 2025 10:46:54 GMT</pubDate>
            <atom:updated>2025-11-05T20:38:57.405Z</atom:updated>
            <content:encoded><![CDATA[<h3>Stop Leaking Your Secrets: Solving the Hidden Secret Problem in Web Apps</h3><p>Every frontend developer hits this question at some point —</p><p>“Where should I store my API key so no one can steal it?”</p><p>Imagine you’re running a modern web app — let’s say Angular — and it needs to call an external API. Maybe you’re submitting contact information or fetching restricted data from a backend that expects an API key for authentication.</p><p>Here’s the problem:<br>If you bundle that key anywhere in your frontend code, anyone can extract it. Doesn’t matter if you minify, obfuscate, or base64 it — your users can still open DevTools and grab it.</p><p>So… what’s the right way?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*yxXi_U_1op04UkTY" /><figcaption>Photo by <a href="https://unsplash.com/@ikukevk?utm_source=medium&amp;utm_medium=referral">Kevin Ku</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><h3>The Real Solution: Use Server-Side Rendering (SSR)</h3><p>Instead of storing secrets in your frontend, the solution relies on server-side rendering (SSR) — specifically, using the Node.js server that powers <a href="https://angular.dev/guide/ssr">Angular SSR </a>as a secure middle layer.</p><p>Think of it like this: Your Angular SSR server becomes a small proxy, sitting between your browser and the real API.</p><p>The browser never sees the secret, and your backend never talks directly to the client.</p><p>Let’s jump straight into an example.</p><h3>Hiding API Keys with Angular SSR Hydration</h3><p>In this example, we want to call an endpoint:</p><pre>POST /api/v1/contact</pre><p>to send some JSON payload, a simple REST-style request. But the endpoint expects an API key in the header, and we don’t want that key to ever reach the browser or be visible in our deployed Angular bundle.</p><p>Assuming you’ve already set up Angular SSR (if not, check the official guide here: <a href="https://angular.dev/guide/ssr">Angular SSR Guide</a>), we’ll extend our Node server to securely handle that API key.</p><h3>Add a Secure Proxy Middleware in server.ts</h3><p>Open your server.ts (the file bootstrapping your SSR server) and add the following code:</p><pre>import { createProxyMiddleware } from &#39;http-proxy-middleware&#39;;<br><br>app.use(&#39;/api&#39;, (req, _res, next) =&gt; {<br>  console.log(&quot;PROXY&quot;);<br>  req.headers[&#39;x-api-key&#39;] = process.env[&#39;API_KEY&#39;] || &#39;&#39;;<br>  req.headers[&#39;accept&#39;] = &#39;application/json&#39;;<br>  next();<br>});<br><br>app.use(<br>  &#39;/api&#39;,<br>  createProxyMiddleware({<br>    target: process.env[&#39;BACKEND_URL&#39;] || &#39;http://localhost:5555/api&#39;,<br>    changeOrigin: true,<br>  }),<br>);</pre><p>What’s happening here:</p><ul><li>We expose /api as a local route handled by the Node server (for example, <a href="http://localhost:4200/api).">http://localhost:4200/api).</a></li><li>Before forwarding the request, the middleware injects your <strong>API key</strong> from an <strong>environment variable</strong>.</li><li>You can set this variable at deployment level — via Docker Compose, Kubernetes, or your cloud platform — so it’s never baked into your frontend code.</li></ul><h3>Update Your Angular Service to Use the Proxy</h3><p>Now, instead of calling the real API endpoint directly, you’ll point your frontend to the proxy path. That means instead of doing:</p><pre>baseUrl = &#39;https://your-real-api.server/api/v1/information&#39;;</pre><p>You simply call:</p><pre>baseUrl = &#39;/api/v1/information&#39;;</pre><p>Here’s a quick example service using Angular’s HttpClient:,</p><pre>import { inject, Injectable } from &#39;@angular/core&#39;;<br>import { HttpClient } from &#39;@angular/common/http&#39;;<br>import { Observable } from &#39;rxjs&#39;;<br><br>@Injectable({<br>  providedIn: &#39;root&#39;<br>})<br>export class CaLoader {<br>  private readonly httpClient = inject(HttpClient);<br>  private readonly baseUrl = &#39;/api/v1/information&#39;;<br><br>  public getAllData(page: number = 0, size: number = 15): Observable&lt;any&gt; {<br>    return this.httpClient.get(`${this.baseUrl}?page=${page}&amp;size=${size}`);<br>  }<br>}</pre><h3>Run It and Observe</h3><p>Start your SSR app, make a request, and check your server logs, you’ll see something like this:</p><pre>Page reload sent to client(s).<br>Server bundles<br>Initial chunk files | Names  | Raw size<br>server.mjs          | server | 3.31 kB |<br>Application bundle generation complete. [0.193 seconds] - 2025-11-05T10:14:40.332Z<br>Page reload sent to client(s).<br>PROXY</pre><p>If you open your browser’s <strong>network inspector</strong> or inspect your compiled Angular bundle, you’ll notice something crucial:<br><strong>No trace of your API key or secrets anywhere.</strong></p><p>Your frontend stays clean. Your secret stays hidden. Mission accomplished.</p><h3>Why This Works</h3><ul><li><strong>The API key never leaves the server.</strong><br> The browser sends requests to your SSR Node server, not directly to the backend.</li><li><strong>Secrets come from environment variables.</strong><br> They’re injected at runtime, not build time, perfect for cloud-native setups.</li><li><strong>Same code, safer architecture.</strong><br> Your Angular services don’t need to know anything about authentication headers.</li></ul><h3>Recap</h3><p>If you’re embedding secrets in your frontend code, they’re not secrets anymore. The right approach is to shift secret handling to the server layer. In Angular SSR, that’s super easy, just proxy your /api routes, inject environment secrets, and let the server handle authentication behind the scenes.</p><p>Written with ❤️ by Jens from <a href="https://fivesec.de/en/fivesec">https://fivesec.de</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5b88bc1347ed" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to manage DNS (BIND9) via REST API using Springboot]]></title>
            <link>https://medium.com/@js_9757/how-to-manage-dns-bind9-via-rest-api-using-springboot-7f57e5fc1a80?source=rss-1d907e2b272e------2</link>
            <guid isPermaLink="false">https://medium.com/p/7f57e5fc1a80</guid>
            <category><![CDATA[dns]]></category>
            <category><![CDATA[cloud]]></category>
            <category><![CDATA[coding]]></category>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[devops]]></category>
            <dc:creator><![CDATA[Jens@Fivesec]]></dc:creator>
            <pubDate>Wed, 24 Sep 2025 16:45:11 GMT</pubDate>
            <atom:updated>2025-09-24T16:45:11.727Z</atom:updated>
            <content:encoded><![CDATA[<p>Managing DNS Resource Records (RR) usually means manually editing BIND configuration files — zone files, records, and all the tiny details that come with them. This process works, but it’s far from user-friendly.</p><p>By contrast, when we use hyperscalers like AWS or GCP — or services like Cloudflare — we get polished dashboards and simple user interfaces. Behind the scenes, these tools almost always talk to DNS servers via REST APIs, handling the complexity for us.</p><p>But how does this actually work? And more importantly: how can we build our own REST management API for a self-hosted DNS server like BIND9?</p><p>The final product can be found on Github here: <a href="https://github.com/fivesecde/fivesec-dns-bind-rest-api">https://github.com/fivesecde/fivesec-dns-bind-rest-api</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*SDBsW7gQZNjnbxID" /><figcaption>Photo by <a href="https://unsplash.com/@sangharsh_l?utm_source=medium&amp;utm_medium=referral">Sangharsh Lohakare</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><h3>DNS and BIND Basics</h3><p>DNS is one of the fundamental building blocks of the internet. Without it, we’d be stuck memorizing thousands of IP addresses just to reach our favorite websites.</p><p>At its core, DNS translates Fully Qualified Domain Names (FQDNs) — like fivesec.de — into IP addresses. This process is called a forward lookup.</p><p>The reverse also works: given an IP address, DNS can resolve it back to a hostname, which is known as a reverse lookup.</p><p>In BIND, these functions are implemented through forward lookup zones and reverse lookup zones.</p><h4><strong>Example BIND Configuration</strong></h4><p><strong>/etc/bind/named.conf.local</strong></p><pre><br>zone &quot;example.com&quot; {<br>    type master;<br>    file &quot;/etc/bind/zones/db.example.com&quot;;<br>};<br><br>zone &quot;2.0.192.in-addr.arpa&quot; {<br>    type master;<br>    file &quot;/etc/bind/zones/db.192.0.2&quot;;<br>};</pre><p><strong>/etc/bind/zones/db.example.com</strong></p><pre>$TTL    604800<br>@       IN      SOA     ns1.example.com. admin.example.com. (<br>                        2025092401 ; Serial (yyyymmddnn)<br>                        604800     ; Refresh<br>                        86400      ; Retry<br>                        2419200    ; Expire<br>                        604800 )   ; Negative Cache TTL<br><br>; Name servers<br>        IN      NS      ns1.example.com.<br>        IN      NS      ns2.example.com.<br><br>; A records<br>ns1     IN      A       192.0.2.1<br>ns2     IN      A       192.0.2.2<br>www     IN      A       192.0.2.10<br>mail    IN      A       192.0.2.20<br><br>; MX record<br>@       IN      MX 10   mail.example.com.</pre><p><strong>/etc/bind/zones/db.192.0.2</strong></p><pre>$TTL    604800<br>@       IN      SOA     ns1.example.com. admin.example.com. (<br>                        2025092401 ; Serial<br>                        604800     ; Refresh<br>                        86400      ; Retry<br>                        2419200    ; Expire<br>                        604800 )   ; Negative Cache TTL<br><br>; Name servers<br>        IN      NS      ns1.example.com.<br>        IN      NS      ns2.example.com.<br><br>; PTR records<br>1       IN      PTR     ns1.example.com.<br>2       IN      PTR     ns2.example.com.<br>10      IN      PTR     www.example.com.<br>20      IN      PTR     mail.example.com.</pre><p>Managing these DNS entries usually means manually editing the zone files. Every time you want to add a new host, change an IP address, or adjust an MX record, you have to open the file, modify it by hand, update the serial number, and reload BIND.</p><p>It works, but it’s tedious, error-prone, and doesn’t scale well — especially if DNS changes happen frequently.</p><h3>Dynamic Updates and TSIG Keys</h3><p>Instead of editing zone files directly, BIND also supports dynamic updates through the DNS UPDATE mechanism (<a href="https://datatracker.ietf.org/doc/html/rfc2136">RFC 2136</a>)<br>. This allows us to add, change, or remove DNS records at runtime — without touching the zone files manually.</p><p>Of course, we don’t want just anyone on the internet to be able to change our DNS zones. That’s where TSIG keys (Transaction Signatures) come in. TSIG is a shared-secret mechanism based on HMAC that authenticates DNS update requests.</p><p>Here’s how it works in practice:</p><ol><li>We generate a TSIG key.</li><li>The DNS client uses the key to sign its update request.</li><li>The BIND server validates the signature before applying the change.</li></ol><p><strong>Creating a TSIG Key</strong></p><pre>sudo tsig-keygen -a hmac-sha256 mydnskey &gt; /etc/bind/keys/ddns.key</pre><p>This creates a file like:</p><pre>key &quot;ddns&quot; {<br>    algorithm hmac-sha256;<br>    secret &quot;dGhpc2lzYWZha2VleGFtcGxlc2VjcmV0Cg==&quot;;<br>};</pre><p>In order to configure bind to use you generated transaction key, you have to add it to your configured zone file (named.conf.local)</p><pre>zone &quot;example.com&quot; {<br>    type master;<br>    file &quot;/etc/bind/zones/db.example.com&quot;;<br>    allow-update { key ddns-key; };<br>};<br><br>zone &quot;2.0.192.in-addr.arpa&quot; {<br>    type master;<br>    file &quot;/etc/bind/zones/db.192.0.2&quot;;<br>    update-policy {<br>        grant ddns-key zonesub ANY;<br>    };<br>};</pre><p>With the key in place, you can now send updates to your BIND instance.</p><h3>Running BIND9 with Docker Compose</h3><p>Now that we’ve secured our BIND setup with a TSIG key, the next step is making it easy to run and test. Instead of installing BIND directly on your host, let’s containerise it with Docker Compose.</p><p>To keep things simple and reproducible, let’s run BIND9 inside a Docker container. This way, we don’t have to install it directly on our host machine, and we can easily mount our own configuration and zone files.</p><pre>services:<br>  bind:<br>    image: ubuntu/bind9:latest<br>    container_name: bind<br>    ports:<br>      - &quot;5553:53/udp&quot;<br>      - &quot;5553:53/tcp&quot;<br>    volumes:<br>      - ./bind/named.conf:/etc/bind/named.conf<br>      - ./bind/named.conf.local:/etc/bind/named.conf.local<br>      - ./bind/named.conf.options:/etc/bind/named.conf.options<br>      - ./bind/zones:/var/lib/bind/zones<br>      - ./bind/ddns.key:/etc/bind/keys/ddns.key:ro<br>    restart: unless-stopped<br>    user: &quot;100:101&quot;</pre><p>Remember: you need to create all mounted files. Examples are provided above or in the GitHub repository: <a href="https://github.com/fivesecde/fivesec-dns-bind-rest-api/blob/main/backend/compose.yaml">https://github.com/fivesecde/fivesec-dns-bind-rest-api/blob/main/backend/compose.yaml</a></p><h3>Using Springboot to managing DNS records</h3><p>The full source code is available on <a href="https://github.com/fivesecde/fivesec-dns-bind-rest-api">GitHub</a>, so I won’t cover every single detail here. Instead, we’ll focus on the core functionality you need to get started.</p><p>One of the most important dependencies for our implementation is <a href="https://github.com/dnsjava/dnsjava"><strong>dnsjava</strong></a>. It’s a mature Java library for handling DNS operations, including queries, updates, and zone transfers. Using dnsjava, we can easily construct and send dynamic update requests to BIND9 without having to reinvent the wheel.</p><h4>Example DNS Update Client Component</h4><p>Full code example can be found here: <a href="https://github.com/fivesecde/fivesec-dns-bind-rest-api/tree/main/backend/src/main/kotlin/de/fivesec/cloud/core/dns">https://github.com/fivesecde/fivesec-dns-bind-rest-api/tree/main/backend/src/main/kotlin/de/fivesec/cloud/core/dns</a></p><p>Here’s a preview for handling A records:</p><pre>package de.fivesec.cloud.core.dns.component<br><br>import de.fivesec.cloud.core.dns.configuration.FvscDnsConfiguration<br>import de.fivesec.cloud.core.dns.exceptions.BindException<br>import org.slf4j.Logger<br>import org.slf4j.LoggerFactory<br>import org.springframework.stereotype.Component<br>import org.xbill.DNS.*<br><br>@Component<br>class DnsUpdateClientComponent(<br>    private val fvscDnsConfiguration: FvscDnsConfiguration,<br>) {<br><br>    fun addARecord(zone: String, name: String, ttl: Long, address: String) {<br>        val update = Update(zoneName(zone))<br><br><br>        update.add(<br>            ARecord(<br>                fqdn(name, zone),<br>                DClass.IN,<br>                ttl,<br>                Address.getByAddress(address)<br>            )<br>        )<br>        sendUpdate(update)<br>    }<br><br><br><br><br>    private fun sendUpdate(update: Update) {<br>        try {<br><br>            LOG.atInfo().setMessage(&quot;resolve dns server&quot;).addKeyValue(&quot;server&quot;, fvscDnsConfiguration.dnsServerAddress)<br>                .addKeyValue(&quot;port&quot;, fvscDnsConfiguration.port).log()<br><br>            val resolver = SimpleResolver(fvscDnsConfiguration.dnsServerAddress)<br>            resolver.port = fvscDnsConfiguration.port<br>            resolver.tcp = false<br>            resolver.tsigKey = TSIG(TSIG.HMAC_SHA256, fvscDnsConfiguration.dnsKeyName, fvscDnsConfiguration.dnsKey)<br><br>            val response = resolver.send(update)<br><br>            LOG.atInfo().setMessage(&quot;got response from dns server&quot;)<br>                .addKeyValue(&quot;header&quot;, response.header)<br>                .addKeyValue(&quot;opcode&quot;, response.header.rcode)<br>                .addKeyValue(&quot;server&quot;, fvscDnsConfiguration.dnsServerAddress)<br>                .addKeyValue(&quot;port&quot;, fvscDnsConfiguration.port).log()<br><br>            if (response.header.rcode != Rcode.NOERROR) {<br>                throw BindException(<br>                    message = &quot;Bind response: ${response.header}&quot;<br>                )<br>            }<br><br>        } catch (e: Exception) {<br>            LOG.atError().setCause(e).setMessage(&quot;Error while sending update&quot;).log()<br>            throw e<br>        }<br>    }<br><br>    private fun fqdn(name: String, zone: String): Name {<br>        val fq = if (name.endsWith(zone)) name else &quot;$name.$zone&quot;<br>        return Name.fromString(fq, Name.root)<br>    }<br><br>    private fun zoneName(zone: String): Name =<br>        Name.fromString(zone, Name.root)<br><br>    companion object {<br>        val LOG: Logger = LoggerFactory.getLogger(DnsUpdateClientComponent::class.java)<br>    }<br>}</pre><p>This component handles building and sending signed DNS update requests. In the full project, you’ll find support for additional record types and error handling.</p><h3>Wrapping It in a REST API</h3><p>With the DnsUpdateClientComponent in place, it’s straightforward to expose REST endpoints using Spring Boot controllers. For example, a POST /api/v1/dns endpoint could call addARecord() behind the scenes — giving you Cloudflare-like functionality for your own BIND server.</p><pre>package de.fivesec.cloud.core.dns.controller<br><br>import de.fivesec.cloud.core.dns.dto.DnsRecordDto<br>import de.fivesec.cloud.core.dns.dto.DnsRecordRequest<br>import de.fivesec.cloud.core.dns.exceptions.ErrorMessageDto<br>import de.fivesec.cloud.core.dns.mapping.asDnsRecordDto<br>import de.fivesec.cloud.core.dns.service.DnsService<br>import jakarta.validation.Valid<br>import org.springframework.http.HttpStatus<br>import org.springframework.web.bind.annotation.*<br>import java.util.*<br><br>@RestController<br>@RequestMapping(&quot;/api/v1/dns&quot;)<br>class DnsController(<br>    private val dnsService: DnsService<br>) {<br><br>    @ResponseStatus(HttpStatus.CREATED)<br>    @PostMapping<br>    fun createRecord(<br>        @Valid<br>        @RequestBody record: DnsRecordRequest<br>    ): DnsRecordDto {<br>        return dnsService.createRecord(record).asDnsRecordDto()<br>    }<br><br>    @PutMapping(&quot;/{id}&quot;)<br>    fun updateRecord(<br>        @PathVariable(&quot;id&quot;) id: UUID,<br>        @Valid<br>        @RequestBody record: DnsRecordRequest<br>    ): DnsRecordDto {<br>        return dnsService.updateRecord(id, record).asDnsRecordDto()<br>    }<br><br><br>    @DeleteMapping(&quot;/{id}&quot;)<br>    fun deleteRecord(<br>        @PathVariable(&quot;id&quot;) id: UUID,<br>    ) {<br>        dnsService.deleteRecord(id)<br>    }<br><br>    @GetMapping(&quot;/{id}&quot;)<br>    fun getRecord(<br>        @PathVariable(&quot;id&quot;) id: UUID,<br>    ): DnsRecordDto {<br>        return dnsService.getRecord(id)<br>    }<br>}</pre><h3>Conclusion</h3><p>By combining BIND9 with Docker, TSIG-secured updates, and a Spring Boot REST API powered by dnsjava, you get:</p><ul><li>A self-hosted alternative to Cloudflare/AWS DNS APIs</li><li>Automation and integration into your CI/CD pipelines</li><li>A foundation for building your own DNS management dashboard</li></ul><p>DNS doesn’t have to be old-school. With just a few components, you can modernise your setup and manage DNS records as easily as the big players.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7f57e5fc1a80" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Cracking the Coding Interview — The Other Side!]]></title>
            <link>https://medium.com/@js_9757/cracking-the-coding-interview-the-other-side-33a0d1e5ec0d?source=rss-1d907e2b272e------2</link>
            <guid isPermaLink="false">https://medium.com/p/33a0d1e5ec0d</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[interview]]></category>
            <category><![CDATA[hire-developers]]></category>
            <category><![CDATA[coding]]></category>
            <dc:creator><![CDATA[Jens@Fivesec]]></dc:creator>
            <pubDate>Mon, 07 Jul 2025 19:40:58 GMT</pubDate>
            <atom:updated>2025-07-07T19:40:58.254Z</atom:updated>
            <content:encoded><![CDATA[<h3>Cracking the Coding Interview — The Other Side!</h3><p>By now, I’ve read more articles, blog posts, and LinkedIn threads about <em>“Cracking the Coding Interview”</em> than I can count. But that got me thinking — <strong>what about the <em>other</em> side?</strong><br> Who’s actually conducting these interviews?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*xqPee0jiv9Ki0Lg2" /><figcaption>Photo by <a href="https://unsplash.com/@sigmund?utm_source=medium&amp;utm_medium=referral">Sigmund</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>And no, we’re not doing the usual HR small talk here — we’re jumping straight into the tech. After all, in just 90 minutes, we want to get a solid feel for whether someone is a good fit — <strong>technically and personally</strong>.</p><p>Wait — <strong>personally?</strong> Isn’t it enough to just be a good coder? Shouldn’t being able to flip binary trees and recite search algorithms in JavaScript be all it takes?</p><p><strong>Wrong.</strong> Most software projects fail not because people can’t code, but because of poor communication, unclear requirements, interpersonal drama, and internal power struggles.<br> Coding? Every company has their own flavor of that anyway. We’ll teach you <em>our</em> way.</p><p>From my perspective (and yes, it’s <em>just</em> my perspective — feel free to disagree), these are the things I believe matter when conducting a coding interview:</p><h3>1. I Want to Hear Your Thoughts</h3><p>This is usually my icebreaker — and I make it super clear right from the start.<br> The most important thing for me is to shift into <em>conversation mode</em> ASAP.<br> This is not an exam. I want to hear how you think, how you approach problems, and how your ideas come together.</p><h3>2. Be Clear About Who We Are and What We Do</h3><p>This is huge — so many candidates assume we write database drivers, patch the Linux kernel, or build new programming languages.</p><p><strong>Spoiler alert: Nope.</strong></p><p>We build <em>standard</em> projects: frontend, backend, database.<br> Sure, sometimes you need to get creative, use your brain, or come up with a clever solution — but that’s the exception, not the rule.</p><p>Don’t be disappointed — embrace the reality.<br> And honestly, writing “standard” software can be insanely interesting and fun.</p><h3>3. A Picture Says More Than a Thousand Words</h3><p>Not just a poetic line — it’s true.<br> My go-to: a simple diagram with 4 boxes and 3 arrows — <strong>zero technical details</strong> up front, those come as we go.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pcSz8v6FQ6g78Ap5QowRdw.png" /></figure><p>Here’s a prompt:<br> “We want to offer a REST API so our customers can manage DNS entries. Each customer has a UUID.”</p><p><strong>Sample questions:</strong></p><ul><li>What tech stack would you use for frontend, backend, database? Why?</li><li>What would the CRUD endpoints for DNS records look like? Why?</li><li>How would you make sure Customer A can’t edit Customer B’s records? Why?</li><li>How would you handle authentication and authorization? Why?</li><li>SQL or NoSQL? Why?</li><li>yadda yadda… [insert 1,000 more questions here]</li></ul><p>You wouldn’t believe the details (or lack thereof) that candidates come up with in response to something this simple.</p><h3>4. 10 Lines of Code = 10 Minutes of Discussion</h3><pre>class Broker<br>{<br>    public void Connect() { }<br>    public void Disconnect() { }<br>    public void Submit() { }<br>    public void Receive() { }<br>}</pre><p>What do you think about this class?<br> Do you know the <strong>SOLID principles</strong>? Let’s go!<br> “Uhh, maybe the class should be split — it feels kind of messy or off…” — Hey, great instinct! But <em>why</em>?</p><p>This is a great jumping-off point for discussing OOP, code design, and various architectural philosophies.</p><h3>5. Let’s Talk About Logs…</h3><p>Which log message do you like better? Why?</p><pre>[INFO] [2025-07-03T12:34:56Z] User 42 transferred 100.00 to user 99</pre><p>or</p><pre>{<br>  &quot;timestamp&quot;: &quot;2025-07-03T12:34:56Z&quot;,<br>  &quot;level&quot;: &quot;Information&quot;,<br>  &quot;event&quot;: &quot;Transfer&quot;,<br>  &quot;userId&quot;: 42,<br>  &quot;recipientId&quot;: 99,<br>  &quot;amount&quot;: 100.0,<br>  &quot;currency&quot;: &quot;EUR&quot;,<br>  &quot;success&quot;: true<br>}</pre><p><strong>My favorite?</strong> The JSON one.<br> Why? Because we write logs to <em>understand</em> things — especially when something goes wrong.<br> And structured logs? They shine when you’re feeding everything into OpenSearch or similar tools. Nobody wants to grep through unstructured chaos forever.</p><p>Bonus: This is a great moment to talk about debuggers and good old stdout debugging too.</p><p>PS: I wrote about this a while ago →<br> 👉 <a href="https://medium.com/@js_9757/why-we-write-logs-and-why-it-matters-more-than-you-think-e1a79559ce74">Why We Write Logs and Why It Matters More Than You Think</a></p><h3>6. Back to Basics</h3><p>This one’s all about your tech stack, your project experience, and what your day-to-day looked like.</p><p>Examples:</p><ul><li>Do you know OAuth? Great — explain it to me.</li><li>Which ORMs have you used? What did you like or hate about them?</li><li>How do you handle database migrations? What are some common pitfalls?</li><li>Where would you store a secret like a 3rd-party API key in your backend? Why?</li><li>What communication patterns come to mind when you think about microservices? When would you use which?</li><li>…</li></ul><h3>7. Small Talk That Isn’t Small</h3><p>What’s your favorite code editor?<br> Sounds silly, but it says a lot about how someone works and what tooling they care about.</p><p><strong>Warning:</strong> Answers like VIM or EMACS indicate extreme personalities… proceed with caution 😄</p><p>🔥🔥🔥 Do you think AI will replace developers? What are your thoughts on wave-coding and integrating AI into the development process? 🔥🔥🔥</p><h3>8. Oh Shit Git!</h3><p>Used Git before?<br> “Yeah, of course!” — “Alright, alright…”</p><p>Imagine this:<br> We’re both working on a feature that spans frontend and backend.<br> You handle the backend, I do frontend.<br> I finish my part and push to our shared feature branch.</p><p>Now what?<br> What’s your pull strategy? Would you rebase? Why or why not? What are the pros and cons?</p><p><strong>Bonus:</strong><br> How do you handle nasty merge conflicts in a team — aside from screaming?</p><h3>9. The Code Review</h3><p>Ah yes — code reviews: the birthplace of passive aggression and the silent destroyer of team spirit.</p><p>How do you approach a code review?<br> Imagine I say I’ve finished a ticket — what’s your next move?</p><p>How do you give feedback? Do we grab a coffee and talk it through line by line?<br> Or do I get a cold comment like, “Told you last week that this sucks”?</p><p>What’s your take on test coverage? How about code style guidelines?</p><h3>10. My Favorite Question</h3><p>What’s the difference between <strong>encoding</strong>, <strong>encryption</strong>, and <strong>hashing</strong>?</p><p>Careful — it’s a 50/50 trap question.</p><p>From Windows login hashes (yes, even still on Win11… probably?)<br> to people saying <em>“encoding is a type of irreversible encryption”</em>, this question always reveals how deep someone really understands the basics.</p><h3>Final Thoughts</h3><p>Yes, this was written in a casual tone — but none of it is meant to be disrespectful.</p><p><strong>Golden rule:</strong> No candidate is stupid.</p><p>Always stay professional, and give honest feedback at the end:<br> <strong>“It wasn’t the right fit — because…”</strong></p><p>That said, this rough framework has served me really well over the years.<br> We’ve had some truly fantastic conversations — on equal footing, and honestly, sometimes way above mine!</p><p><strong>Being a developer is about <em>so much more</em> than just writing code.</strong></p><p>I hope this gave you some inspiration for your next technical interview!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=33a0d1e5ec0d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[REST API Design: 18 Proven Best Practices for Clean and Efficient Endpoints]]></title>
            <link>https://medium.com/@js_9757/rest-api-design-18-proven-best-practices-for-clean-and-efficient-endpoints-a295ba46c514?source=rss-1d907e2b272e------2</link>
            <guid isPermaLink="false">https://medium.com/p/a295ba46c514</guid>
            <category><![CDATA[java]]></category>
            <category><![CDATA[books]]></category>
            <category><![CDATA[cybersecurity]]></category>
            <category><![CDATA[career-development]]></category>
            <category><![CDATA[api]]></category>
            <dc:creator><![CDATA[Jens@Fivesec]]></dc:creator>
            <pubDate>Tue, 13 May 2025 19:45:51 GMT</pubDate>
            <atom:updated>2025-05-14T07:39:36.799Z</atom:updated>
            <content:encoded><![CDATA[<p><strong>“When it comes to REST API design, there are varying opinions on what the ‘best’ patterns and architectures are. At the end of the day, the decision should be one that’s discussed, defined, and adhered to in a way that’s homogeneous for a product ecosystem or project. Together. As a development team.”</strong></p><p>In this post, I’d like to share what I believe are the most important design rules for building scalable, sustainable, and robust REST APIs.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*KSFT_ByVOsifYwh1" /><figcaption>Photo by <a href="https://unsplash.com/@kellysikkema?utm_source=medium&amp;utm_medium=referral">Kelly Sikkema</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><h3>1. Pragmatism Beats Purism</h3><p>Don’t obsess over being 100% REST-compliant. It’s okay to bend the rules — as long as your API is <strong>clean, consistent, and easy to use</strong>.</p><p>If certain REST conventions don’t make sense in your context, <strong>speak up</strong>. That’s a great reason to start a team discussion, challenge outdated patterns, and evolve your standards together.</p><p>At the end of the day, your API isn’t there to please a spec — it’s there to serve <strong>real developers</strong> with real use cases.</p><h4>Name endpoints with intent</h4><p>Your routes should speak for themselves. Avoid noisy or redundant paths — especially ones that leak internal implementation details like “getById”.</p><pre>BAD:<br>GET /api/get/project<br>GET /api/getById/project?id=123<br><br>GOOD:<br>GET /api/projects<br>GET /api/projects/{projectId}</pre><h3>2. Use Plural Nouns for Resources</h3><p>Always use the <strong>plural form</strong> when naming your resources — even if the endpoint only returns a single item.</p><p>This keeps your API consistent, predictable, and easy to scale. Developers instantly understand that they’re dealing with a collection — and retrieving an individual item from that collection becomes intuitive.</p><pre>BAD:<br>GET /api/get/project<br><br>GET /api/projects<br>GET /api/projects/{projectId}</pre><p>Pluralization helps establish clear patterns across your API. If you’re fetching users, it’s always /users — not /user, not /getUser, not /single-user.</p><p>Consistency wins.</p><h3>3. Embrace Hierarchical Endpoint Design</h3><p>When dealing with <strong>nested or related resources</strong>, use a <strong>hierarchical URL structure</strong> to reflect their relationships. This makes your API more intuitive and transparent — especially for clients trying to understand how resources are connected.</p><p>It’s not about nesting everything — only structure what’s <strong>logically tied together</strong>.</p><pre>BAD:<br>GET /api/evaluation/123/project<br><br>GOOD:<br>GET /api/projects/123/evaluations</pre><p>This makes the relationship crystal clear: you’re retrieving evaluations that belong to a specific project.</p><p><strong>Pro tip</strong>: Don’t over-nest. If a relationship is weak or unnecessary for clarity, keep it flat. Design for readability, not complexity.</p><h3>4. Never Return Primitive Values at the Top Level</h3><p>The top-level structure of your API responses should <strong>always be an object</strong> — <strong>never</strong> a raw array, boolean, string, or number.</p><p>Why? Because wrapping your response in an object gives you the flexibility to <strong>extend your API later without breaking clients</strong>. You can easily add metadata, status fields, or links — all without changing the original contract.</p><pre>BAD:<br>GET /api/projects/123/active<br>Response:<br>true<br><br>GOOD:<br>GET /api/projects/123/active<br>Response:<br>{<br>    &quot;isActive&quot;: true<br>}</pre><p>Now you’ve got room to grow:</p><pre>{<br>  &quot;isActive&quot;: true,<br>  &quot;lastChecked&quot;: &quot;2025-05-13T08:00:00Z&quot;,<br>  &quot;source&quot;: &quot;system-check&quot;<br>}</pre><h3>5. Don’t Return Arrays at the Top Level</h3><p>Just like with primitive values, your API should <strong>never return a raw array at the top level</strong>. Instead, always wrap arrays inside an object.</p><p>Why? Because as your API evolves, you’ll likely want to add <strong>pagination, metadata, or links</strong> — and if you’re returning just an array, you’re locked in.</p><pre>BAD:<br><br>GET /api/projects<br>Response:<br>[<br>  { ...project1... },<br>  { ...project2... }<br>]</pre><p>Looks clean — until you realize you can’t add paging without breaking every client integration.</p><pre>GOOD:<br><br>GET /api/projects<br>Response:<br>{<br>  &quot;data&quot;: [<br>    { ...project1... },<br>    { ...project2... }<br>  ],<br>  &quot;paging&quot;: {<br>    &quot;limit&quot;: 25,<br>    &quot;offset&quot;: 0,<br>    &quot;total&quot;: 142<br>  }<br>}</pre><p>By wrapping the array, you future-proof your API. It also sets up a standard structure for clients to rely on — no surprises.</p><p>Rule of thumb: <strong>Object always. Arrays inside.</strong></p><h3>6. Avoid Returning Map-Like Structures in JSON</h3><p>Returning <strong>maps (keyed objects)</strong> instead of arrays may seem efficient — but it’s usually a trap.</p><p>Here’s why <strong>you should avoid them</strong>:</p><ul><li>Redundant keys bloat your payload. You’re duplicating values already inside the object.</li><li>Dynamic keys are a nightmare for typed languages — they break auto-completion, type safety, and static analysis.</li><li>What you consider a “natural key” today may change tomorrow — and now you’ve locked yourself into a fragile structure.</li></ul><p>Let the client decide how to index data. If they want a map for fast access, they can build one with a one-liner in most languages.</p><pre>BAD:<br><br>GET /api/projects<br>Response:<br>{<br>  &quot;KEY1&quot;: { &quot;id&quot;: &quot;KEY1&quot;, &quot;foo&quot;: &quot;bar&quot; },<br>  &quot;KEY2&quot;: { &quot;id&quot;: &quot;KEY2&quot;, &quot;foo&quot;: &quot;bar&quot; },<br>  &quot;KEY3&quot;: { &quot;id&quot;: &quot;KEY3&quot;, &quot;foo&quot;: &quot;bar&quot; }<br>}</pre><p>This is brittle, hard to type, and inflexible.</p><pre>GOOD:<br><br>GET /api/projects<br>Response:<br>{<br>  &quot;data&quot;: [<br>    { &quot;id&quot;: &quot;KEY1&quot;, &quot;foo&quot;: &quot;bar&quot; },<br>    { &quot;id&quot;: &quot;KEY2&quot;, &quot;foo&quot;: &quot;bar&quot; },<br>    { &quot;id&quot;: &quot;KEY3&quot;, &quot;foo&quot;: &quot;bar&quot; }<br>  ]<br>}</pre><p>This structure is clean, extensible, and safe — and the client can easily transform it if needed.</p><h3>7. Use Kebab-Case for URL Paths</h3><p>All path segments in your API should follow <strong>kebab-case</strong> — lowercase letters with hyphens (-) as separators.</p><p>This isn’t just a style choice — it ensures:</p><ul><li><strong>Consistency</strong> across your API</li><li><strong>Readability</strong> in URLs</li><li><strong>Compatibility</strong> with common tooling and routing systems</li></ul><p>Stick to the pattern: ^[a-z][a-z\-0-9]*$ This means:</p><ul><li>Start with a lowercase letter</li><li>Use only lowercase letters, numbers, or hyphens</li></ul><pre>GOOD:<br>/project/{projectId}/management/reset-members</pre><p>Avoid camelCase, PascalCase, snake_case, or uppercase letters in paths. Keep it clean, URL-friendly, and easy on the eyes.</p><p><strong>TL;DR:</strong> kebab-case your paths — always!</p><h3>8. Always Use Lower Camel Case for Fields &amp; Query Params</h3><p>When it comes to <strong>query parameters</strong> and <strong>payload fields</strong>, consistency is king — and that means sticking to <strong>lower camelCase</strong>.</p><p>Why?</p><ul><li>It aligns with most programming languages (JavaScript, Java, TypeScript, etc.)</li><li>It plays nicely with auto-generated clients and serializers</li><li>It’s predictable and easier to mentally parse</li></ul><pre>BAD:<br><br>GET /api/projects?sort=project_name<br>POST /api/projects<br>{<br>  &quot;project_name&quot;: &quot;Meta&quot;,<br>  &quot;project_age&quot;: 12<br>}<br><br>GOOD:<br><br>GET /api/projects?sort=projectName<br>POST /api/projects<br>{<br>  &quot;projectName&quot;: &quot;Meta&quot;,<br>  &quot;projectAge&quot;: 12<br>}</pre><p>This also prevents confusion across systems. Mixing naming conventions is an easy way to introduce bugs and pain during integration.</p><p><strong>TL;DR:</strong> camelCaseEverything in query params and JSON fields.</p><h3>9. Don’t Use Abbreviations for Property Names</h3><p>Abbreviations might save a few bytes, but they cost you in <strong>readability</strong> and <strong>maintainability</strong>. Don’t fall into the trap of shortening property names for the sake of “efficiency.” Trust me, you’ll thank yourself later when you can actually <strong>read</strong> your own API without scratching your head.</p><pre>BAD:<br><br><br>{<br>  &quot;pId&quot;: &quot;922414a2-5f52-442d-9729-ad456ae30652&quot;,<br>  ...<br>}<br><br>GOOD:<br><br>{<br>  &quot;projectId&quot;: &quot;922414a2-5f52-442d-9729-ad456ae30652&quot;,<br>  ...<br>}</pre><p>Clear, descriptive names are always better than cryptic abbreviations that only you understand… for now. Keep it simple, keep it human.</p><p><strong>TL;DR:</strong> Write out names. It’s worth it.</p><h3>10. Think in Use Cases, Not CRUD Operations</h3><p>When you’re designing an API for a <strong>complex use case</strong>, think in terms of <strong>user actions</strong> rather than just CRUD operations. Instead of forcing the client to figure out what steps need to be executed and in which order, create endpoints that directly represent <strong>business logic</strong>.</p><pre>BAD:<br><br>POST /api/projects<br>PUT /api/projects/123/user/456/assign<br><br>GOOD:<br><br>POST /api/projects/123/assign</pre><p>Now, the API call represents an <strong>action</strong> in the context of the project. It’s simple, intuitive, and clean. The business logic is encapsulated in the endpoint itself, making it much easier for the client to interact with.</p><p><strong>TL;DR:</strong> API actions should map directly to use cases — not a series of CRUD steps.</p><h3>11. Use the Standard Format for Date and Time</h3><p>Date and time should always be in <a href="https://en.wikipedia.org/wiki/ISO_8601"><strong>ISO8601</strong></a> format — it’s the international standard for date-time representation. Although ISO8601 allows time zone offsets, <strong>always provide timestamps in UTC</strong> to avoid ambiguity and timezone headaches.</p><pre>BAD:<br><br>2024-01-12T15:07:17+01:00<br><br>GOOD:<br><br>2024-01-12T14:07:17Z</pre><p>The “Z” at the end of the UTC timestamp signifies <strong>Zulu time</strong> (UTC), making it universally understandable and unambiguous.</p><p><strong>TL;DR:</strong> Use ISO8601 and UTC for date and time — consistency is key.</p><h3>12. API Versioning</h3><p>When an <strong>API change</strong> is <strong>not backward-compatible</strong>, you should release it as a <strong>new version</strong>. This approach ensures clients aren’t suddenly broken by changes.</p><ul><li>The <strong>version number</strong> should be part of the <strong>path</strong>.</li><li>Mark the old version as <strong>deprecated</strong>.</li><li>Once all clients have migrated to the new version, you can remove deprecated APIs.</li></ul><p>This versioning strategy is particularly important when <strong>syntax changes</strong>.</p><p><strong>Example:</strong></p><pre>Deprecated:<br><br>GET /api/projects<br><br>New:<br><br>GET /api/v2/projects</pre><p>If the <strong>semantics</strong> of your API also change (e.g., due to a different use case), it’s recommended to introduce a <strong>new endpoint</strong> to clearly distinguish the updated behavior.</p><p><strong>TL;DR:</strong> Keep versioning in the path, deprecate old versions, and introduce new endpoints for breaking semantic changes.</p><h3>13. Don’t Expose Internal Information</h3><p>Your API should <strong>never expose internal details</strong>, such as <strong>stack traces</strong> or system-level error messages. These can reveal sensitive implementation details that attackers might exploit. Additionally, such information is usually only useful to the <strong>developers</strong>, not the API consumers.</p><p>API users expect <strong>clear, user-friendly error messages</strong>, not the internals of your system. Hiding implementation details helps to keep your API secure and provides a better experience for developers.</p><pre>BAD:<br><br>{<br>  &quot;error&quot;: &quot;Internal Server Error&quot;,<br>  &quot;details&quot;: &quot;Stack trace: [full error details]&quot;<br>}<br><br>GOOD:<br><br>{<br>  &quot;error&quot;: &quot;Something went wrong. Please try again later.&quot;<br>}</pre><p>This way, you maintain security while providing users with the necessary context to handle errors effectively.</p><p><strong>TL;DR:</strong> <strong>Never expose internal errors</strong> — always provide user-friendly error messages.</p><h3>14. Format for Custom Headers</h3><p>When defining custom headers, <strong>do not use the “X-” prefix</strong> (as per RFC6648). Instead, adopt <strong>kebab-case</strong> and use it<strong> </strong>for header names. This aligns with current best practices and helps avoid unnecessary clutter.</p><p>Furthermore, ensure that the server handles these headers <strong>case-insensitively</strong> (see <a href="https://www.rfc-editor.org/rfc/rfc9110.html">RFC9110</a>).</p><p><strong>Example:</strong></p><p>custom-header</p><p>This keeps the headers clear, consistent, and compliant with modern standards.</p><p><strong>TL;DR:</strong> Use <strong>kebab-case</strong> and <strong>uppercase</strong> for custom headers — no more “X-” prefixes.</p><h3>15. Provide API Specification Using OpenAPI</h3><p>One of the best ways to ensure your API is well-documented, consistent, and easy to consume is by providing an <strong>OpenAPI Specification</strong> (formerly Swagger). OpenAPI allows you to define your API structure, endpoints, request/response formats, and more in a standardized, machine-readable format.</p><p>Why OpenAPI?</p><ul><li><strong>Automates Documentation</strong>: It generates interactive, up-to-date docs for your API.</li><li><strong>Client Generation</strong>: Automatically generate SDKs or client libraries for different languages.</li><li><strong>Testing &amp; Validation</strong>: Easily validate requests and responses against your spec, reducing bugs.</li></ul><h3>16. Stick to Conventional Pagination Syntax</h3><p>When providing <strong>pagination support</strong>, it’s crucial to stick to <strong>standard conventions</strong> to ensure consistency and ease of use. This helps clients interact with your API predictably, making the integration smooth and hassle-free.</p><h4>Request Parameters</h4><ul><li><strong>page</strong>: The numeric page number. <strong>0</strong> is the first page. If not provided, the default is <strong>0</strong>.</li><li><strong>size</strong>: The number of items per page. If not specified, the default is <strong>100</strong>.</li></ul><p><strong>Example:</strong></p><pre>GET /projects?page=2&amp;size=15</pre><p>This request will return projects<strong> 31–45</strong> from the collection.</p><h4>Response Schema</h4><ul><li><strong>data</strong>: Contains the elements of the requested page. Its size may be smaller than the requested page size on the last page.</li><li><strong>page</strong>: Provides the paging metadata, ensuring consistent sorting across pages.</li><li><strong>page</strong>: The numeric page number.</li><li><strong>size</strong>: The number of elements per page, which might be smaller than the requested size.</li><li><strong>totalPages</strong>: The total number of pages available in the result set.</li><li><strong>totalElements</strong>: The total number of elements across all pages.</li></ul><p><strong>Example response:</strong></p><pre>{<br>    &quot;data&quot;: [{...}, {...}],<br>    &quot;page&quot;: {<br>        &quot;page&quot;: 2,<br>        &quot;size&quot;: 15,<br>        &quot;totalPages&quot;: 90,<br>        &quot;totalElements&quot;: 1333<br>    }<br>}</pre><h3>17. Stick to Conventional Error Response Format</h3><p>When an error occurs (HTTP status code <strong>≥ 400</strong>), <strong>maintain a consistent error response format</strong>. This helps clients easily interpret and handle errors.</p><h4>Error Response Format</h4><ul><li><strong>status</strong>: The HTTP status in <strong>uppercase</strong> (e.g., <strong>BAD_REQUEST</strong>).</li><li><strong>code</strong>: The <strong>numeric value</strong> of the HTTP status (e.g., <strong>400</strong>).</li><li><strong>timestamp</strong>: The <strong>current timestamp</strong> in ISO 8601 <strong>UTC</strong> format (e.g., <strong>2025–04–20T11:23:15.148431Z</strong>).</li><li><strong>errors</strong>: A list of error details, containing at least one element. Include all relevant validation errors, if applicable.</li></ul><p>Each error detail should include:</p><ul><li><strong>type</strong>: An <strong>application-specific error key</strong> (e.g., <strong>VALIDATION_ERROR</strong>).</li><li><strong>message</strong>: A <strong>human-readable error message</strong> explaining the issue.</li><li><strong>field</strong> (optional): The field or query parameter related to the error.</li></ul><p><strong>Example:</strong></p><pre>HTTP 400 Bad Request<br>{<br>  &quot;status&quot;: &quot;BAD_REQUEST&quot;,<br>  &quot;code&quot;: 400,<br>  &quot;timestamp&quot;: &quot;2025–04–20T11:23:15.148431Z&quot;,<br>  &quot;errors&quot;: [<br>    {<br>      &quot;type&quot;: &quot;VALIDATION_ERROR&quot;,<br>      &quot;message&quot;: &quot;Provided value does not match pattern&quot;,<br>      &quot;field&quot;: &quot;key&quot;<br>    },<br>    {<br>      &quot;type&quot;: &quot;VALIDATION_ERROR&quot;,<br>      &quot;message&quot;: &quot;Field is missing&quot;,<br>      &quot;field&quot;: &quot;test&quot;<br>    }<br>  ]<br>}</pre><h3>18. Stick to Conventional Search Syntax (simple search)</h3><p>When offering a <strong>search feature</strong> (especially when filters are not enough), it’s crucial to follow <strong>conventional syntax</strong> for search queries to ensure consistency and ease of use. The primary use case is when you want to search across multiple attributes in a <strong>full-text</strong> manner.</p><h4>Search Convention</h4><ul><li><strong>q</strong>: The API should use the provided value for <strong>full-text search</strong> across all supported fields of the entity. It must be clearly documented which fields the search is applied to.</li></ul><p><strong>Example:</strong></p><pre>GET /projects?q=demo</pre><p>This query will search for the term demo across all search-supported attributes of the entity, returning results where any field matches the search term.</p><p><strong>TL;DR:</strong> Use a simple <strong>search syntax</strong> with a clear q parameter to search across multiple attributes, ensuring consistent and easy usage.</p><h3>Whats next?</h3><p>In this article, we explore essential best practices for designing REST APIs that are scalable, sustainable, and maintainable. From naming conventions to pagination, error handling, and versioning, we cover key principles every developer should follow to create clean and efficient APIs. With a focus on practicality and consistency, these guidelines help ensure your APIs are easy to use, extend, and maintain, whether for internal projects or external services. By adhering to these design rules, teams can avoid common pitfalls and ensure long-term success in their API development efforts.</p><p>Written with ❤️ by <a href="https://fivesec.de/en/fivesec">https://fivesec.de/en/fivesec</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a295ba46c514" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why We Write Logs (and Why It Matters More Than You Think)]]></title>
            <link>https://medium.com/@js_9757/why-we-write-logs-and-why-it-matters-more-than-you-think-e1a79559ce74?source=rss-1d907e2b272e------2</link>
            <guid isPermaLink="false">https://medium.com/p/e1a79559ce74</guid>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[coding]]></category>
            <category><![CDATA[cybersecurity]]></category>
            <category><![CDATA[opensearch]]></category>
            <category><![CDATA[siem]]></category>
            <dc:creator><![CDATA[Jens@Fivesec]]></dc:creator>
            <pubDate>Thu, 24 Apr 2025 19:28:49 GMT</pubDate>
            <atom:updated>2025-04-24T19:28:49.805Z</atom:updated>
            <content:encoded><![CDATA[<p>According to <em>IBM’s 2024 Cost of a Data Breach Report</em>, the average time to detect a data breach is 200 days. Add another 70 days to contain it, and you’re looking at a 270-day breach lifecycle.</p><p>So, what can we do — as a (tech)company, an engineering team, or a cybersecurity agency — to fight back?</p><p>Let’s start at the very beginning of the security chain: <strong>logs</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*pqotIbhXWH1_w_C8" /><figcaption>Photo by <a href="https://unsplash.com/@freddymarschall?utm_source=medium&amp;utm_medium=referral">Frederick Marschall</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><h3>But wait — why do we even write logs?</h3><p>At first glance, that might seem like a trivial question. But if you pause for a second, there’s a lot more depth to it. Who are we actually writing logs for? Is it for ourselves as engineers? For the operations and monitoring team? Or maybe for the security analysts?</p><p>The answer is: all of them. First and foremost, we write logs for the teams that operate and secure our applications. Logs are the digital breadcrumbs that help us trace what happened, when it happened, and why it happened. They’re not just for debugging — they’re a core part of observability, incident response, and digital forensics.</p><h3>What’s Even in a Log Line?</h3><p>Let’s be honest: a log message like</p><pre>Function users() return list[0x34]</pre><p>…is completely meaningless.</p><p>What’s missing? Well, ask yourself: What are we supposed to do with this information?<br>No clue? Same here.</p><p>So, how can we make this log message actually useful? The first step: structure.</p><p>Instead of raw, unstructured strings, we should embrace structured logging. JSON is a great format for this — it’s machine-readable, easy to parse, and integrates well with modern log aggregators.</p><pre>{<br>  &quot;message&quot;: &quot;Function users() return list[0x34]&quot;<br>}</pre><p>Okay, better. But still, the value here is almost zero. What are we trying to communicate? What’s the context?</p><p>Let’s level it up.</p><p>Imagine we’re logging a response from a typical API endpoint — say, GET /users, which returns a list of all users. Here’s what a meaningful, structured log might look like:</p><pre>{<br>  &quot;message&quot;: &quot;getting list of all users&quot;,<br>  &quot;timestamp&quot;: &quot;2025-04-24T16:36:08.272577379Z&quot;,<br>  &quot;user-length&quot;: 200,<br>  &quot;session-id&quot;: &quot;123&quot;,<br>  &quot;trace-id&quot;: &quot;456&quot;,<br>  &quot;user-id&quot;: &quot;9f222efdfe65cba09c5726666c001f106a7fcd268abd1cea40c5a21b8a670e90&quot;,<br>  &quot;user-name&quot;: &quot;admin&quot;,<br>  &quot;customer&quot;: &quot;example ltd&quot;<br>}</pre><p>Now we’re talking.</p><p>We’ve got a timestamp, a traceable user session, a unique request ID, and even metadata about the user and customer. This kind of log entry allows for correlation across systems, time-based aggregation, root cause analysis — and yes, actual security monitoring.</p><h3>Who Are We Writing Logs For — And Where Do They All Go?</h3><p>In most cases, the best way to get this right is by collaborating across teams — engineering, operations, and security — and translating those needs into clear logging guidelines.</p><p>But even with well-defined rules, can we really claim to have full control over our deployment’s logging behavior?</p><p>Probably not.</p><p>Why? Because beyond the code we write ourselves, we rely on a host of other components:<br> <strong>NGINX</strong>, <strong>Traefik</strong>, <strong>Kubernetes</strong>, <strong>the operating system</strong> — each with its own logging mechanisms.</p><p>For example, I’ve written a separate article on how to harden and log effectively with NGINX:<br><a href="https://medium.com/@js_9757/building-a-hardened-nginx-with-docker-brotli-and-advanced-logging-f27457e78931">Building a Hardened NGINX with Docker, Brotli and Advanced Logging</a></p><p>The big question is: <strong>how do we collect all these logs — and where do we store them?</strong></p><p>Personally, I’m a big fan of open source solutions, and my go-to choice here is <strong>OpenSearch</strong>.</p><p>It gives us more than just log aggregation through tools like <strong>Logstash</strong> — we also get advanced capabilities like <strong>anomaly detection</strong> and <strong>security analytics</strong> via its SIEM features.</p><p>So instead of just dumping logs into a file or black box, we’re enabling observability, traceability, and proactive defense across the entire stack.</p><h3>From Containers to Insights: Shipping Logs with Logstash and OpenSearch</h3><p>If you’re ready to get hands-on, I’ve already published a simple OpenSearch SIEM starter template: <a href="https://github.com/fivesecde/fivesec-opensearch-siem-starter">fivesec-opensearch-siem-starter on GitHub</a></p><p>This setup already includes <strong>NGINX configured with JSON logging</strong>, and all logs are piped through <strong>Logstash</strong> directly into <strong>OpenSearch</strong>.</p><p>But here’s the real kicker: if you’re running your services in Docker, there’s an easy way to forward logs from stdout directly to your OpenSearch stack—<strong>without extra agents inside your containers</strong>.</p><p>Docker supports the <strong>GELF (Graylog Extended Log Format)</strong> log driver, which lets you forward logs over UDP with just a few lines in your docker-compose.yml:</p><pre>logging:<br>  driver: gelf<br>  options:<br>    gelf-address: &quot;udp://127.0.0.1:5000&quot;<br>    tag: docker.&lt;your-deployment-name&gt;</pre><p>This will send logs to a local Logstash instance listening on port 5000.</p><p>Your <strong>Logstash service</strong> can be configured like this:</p><pre>logstash:<br>  image: opensearchproject/logstash-oss-with-opensearch-output-plugin<br>  container_name: logstash<br>  volumes:<br>    - ./logstash.conf:/usr/share/logstash/pipeline/logstash.conf<br>  ports:<br>    - &quot;5000:5000/udp&quot;</pre><p>With this setup, you can seamlessly ship logs from all your containers and supporting infrastructure into OpenSearch — with full structure, context, and searchability.</p><h3>TL;DR — Why We Write Logs (And How to Do It Right)</h3><p>Logs are more than just debug output — they’re a foundational part of observability, incident response, and cybersecurity.</p><ul><li><strong>Start with intention:</strong> Ask <em>who</em> you’re writing logs for and <em>what</em> they need to see.</li><li><strong>Use structured logging:</strong> JSON format is your friend — machine-readable, searchable, and consistent.</li><li><strong>Capture context:</strong> Include metadata like timestamps, user/session IDs, trace IDs, and application context.</li><li><strong>Think beyond your code:</strong> Apps, proxies, orchestrators, the OS — every layer logs. You need to collect it all.</li><li><strong>Centralize your logs:</strong> Use tools like <strong>Logstash</strong> and <strong>OpenSearch</strong> to unify and analyze logs across your stack.</li><li><strong>Make it actionable:</strong> Enable anomaly detection, correlation, and real-time threat analysis with OpenSearch SIEM.</li></ul><p>I’ve shared a ready-to-use GitHub starter — so there’s no excuse to treat logging as an afterthought anymore.</p><p>Logs are your first signal. Let’s make them count.</p><p>Written with ❤️ by <a href="https://fivesec.de/en/fivesec">https://fivesec.de/en/fivesec</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e1a79559ce74" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>