Aegis is a library that allows you detect if your software is being debugged or not on Linux, FreeBSD, NetBSD, OpenBSD and Windows. You can use it natively from C or use the Go bind.

The name is about a lousy acronym: An ELF's -g inspection signalling. If you are hooked on Greek mythology you should know that Aegis is the name of the shield gave by Athena to Perseus to help him kill Medusa. If you are using it from Windows understand as An Executable's -g inspection signalling ;)

On Windows we have plenty of ways to easily do this kind of detection. Opposingly, on Unix world we do not have any standard way. Aegis is an attempt of filling up this gap.

You can use Aegis as an anti-debugging mitigation or as a debugging facility. It just depends on you and your current requirements.

Originally, I wrote this library to use on another tool of mine called blackcat as an anti-debugging stuff.

Remark: In order to make this anti-debug resilient against library hooking you always should link your software static. Moreover, if you want to keep eavesdroppers out as much as possible: link your software static. Otherwise there is no necessity of worrying about none of it. Because your front door is wide open or you do not have even a door! Haha!

Back

Debugging detection

In some bug hunting cases is useful to wait for debugger before continuing the program execution. Specially concurrent stuff or even event oriented processing. In this case you can use aegis_has_debugger() function.

This function returns 1 when a debugger has being attached otherwise 0.

The following program will wait for debugger before exiting:

#include <aegis.h>
#include <stdlib.h>
#include <stdio.h>
#include <unistd.h>
#include <signal.h>

void sigint_watchdog(int signo) {
    printf("\nCanceled.\n");
    exit(1);
}

int main(int argc, char **argv) {
    signal(SIGINT, sigint_watchdog);
    signal(SIGTERM, sigint_watchdog);
    printf("*** Waiting for debug attachment (pid=%d)...\n", getpid());
    while (!aegis_has_debugger()) {
        usleep(1);
    }
    printf("*** Debugger is attached.\n");
    return 0;
}

The program above can be found at src/samples sub-directory under the name wait4debug.c. The manual compilation of this code is fairly simple and involves:

To indicate where aegis.h is found.
To indicate where libaegis.a is found.
To pass -laegis flag to linker.
To pass -lpthread flag if you are on Linux, FreeBSD, NetBSD or OpenBSD.

All in one compilation line:

black-beard@QueensAnneRevenge:~/src/aegis/src# cd samples
black-beard@QueensAnneRevenge:~/src/aegis/src/samples# gcc -I.. -L../../lib \
> wait4debug.c -owait4debug -laegis
black-beard@QueensAnneRevenge:~/src/aegis/src/samples# _

Back

Testing `wait4debug`

On a terminal run wait4debug:

black-beard@QueensAnneRevenge:~/src/aegis/src/samples# ./wait4debug
*** Wait for debug attachment (pid=29670)

wait4debug has facilitate the things for you by giving its pid. Now on another terminal run GDB as follows:

black-beard@QueensAnneRevenge:~# gdb attach 29670
(...)
(gdb)

You will attach to the wait4debug process, now let's continue on GDB:

black-beard@QueensAnneRevenge:~# gdb attach 29670
(...)
(gdb) continue
Continuing.
[Inferior 1 (process 29670) exited normally]
(gdb)

Nice, the program has exited. If you back to your wait4debug terminal you will see something like:

black-beard@QueensAnneRevenge:~/src/aegis/src/samples# ./wait4debug
*** Wait for debug attachment (pid=29670)
*** Debugger is attached.
black-beard@QueensAnneRevenge:~/src/aegis/src/samples# _

Back

Debugging mitigation

Certain programs require some debugging avoidance. Aegis features a nice and straightforward way to implement this kind of mitigation. For doing that you need:

To implement a exit checking function with the prototype: int(void *). A return different from zero means that gorgon should exit.
If necessary to implement a on debugger function with the prototype: void(void *). This function will be called when a debugger is detected.
To call aegis_set_gorgon() passing your exit checking function and its argument pointer, besides on debugger function and its argument pointer.

Take a look at the following code to get more details about:

/*
 * Copyright (c) 2020, Rafael Santiago
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of this source tree.
 */
#include <aegis.h>
#include <stdlib.h>
#include <unistd.h>
#include <stdio.h>
#include <signal.h>

int bye = 0;

void sigint_watchdog(int signo) {
    bye = 1;
}

int disable_gorgon(void *args) {
    return (*(int *)args);
}

void on_debugger(void *args) {
    fprintf(stdout, "\ninfo: debugger detected.\n");
    exit(1);
}

int main(int argc, char **argv) {
    signal(SIGINT, sigint_watchdog);
    signal(SIGTERM, sigint_watchdog);
    if (aegis_set_gorgon(disable_gorgon, &bye, on_debugger, NULL) != 0) {
        fprintf(stderr, "error: unable to set gorgon.\n");
        exit(1);
    }

    fprintf(stdout, "info: process started (pid=%d)...\n", getpid());
    while (!bye) {
        usleep(2);
    }

    fprintf(stdout, "\ninfo: gracefully exiting, no debugger was detected.\n");

    return 0;
}

You can find the presented code into src/samples/setgorgon.c.

When on debugger function was passed as NULL. It asks aegis to use its default on debugger function. This default callback is only about calling exit(1). Thus, after a debugger detection, the process will immediately exit. There are some cases that you need to do something before exiting, for those cases on debugger function would be handy. Anyway, once a debugger attached, the best action is terminate the process as soon as possible or try to kill the debugger.

Back

Testing `setgorgon`

On a terminal run setgorgon

black-beard@QueensAnneRevenge:~/src/aegis/src/samples# ./setgorgon
info: process started (pid=28582)...

Now let's only press ctrl + c:

black-beard@QueensAnneRevenge:~/src/aegis/src/samples# ./setgorgon
info: process started (pid=28582)...
^C
info: gracefully exiting, no debugger was detected.
black-beard@QueensAnneRevenge:~/src/aegis/src/samples# _

Nice but what about give debugging a try? Let's run it again:

black-beard@QueensAnneRevenge:~/src/aegis/src/samples# ./setgorgon
info: process started (pid=14753)...

On another terminal let's attach GDB:

black-beard@QueensAnneRevenge:~# gdb attach 14753
(...)
(gdb) _

Now, still on GDB continue the setgorgon process:

black-beard@QueensAnneRevenge:~# gdb attach 14753
(...)
(gdb) continue
Continuing.
[Thread 0x7f47880ec700 (LWP 14754) exited]
[Inferior 1 (process 14753) exited with code 01]
(gdb) _

No chance for our debugging attempt, let's go back to our setgorgon's terminal:

black-beard@QueensAnneRevenge:~/src/aegis/src/samples# ./setgorgon
info: process started (pid=14753)...

info: debugger detected.
black-beard@QueensAnneRevenge:~/src/aegis/src/samples# _

No gracefully exiting message, it was really aborted to avoid debugging. Our gorgon has done her job.

Maybe you are asking why call this feature of Gorgon. Well, Perseus myth tells that Athena gave him a shield (aegis) for help him to kill Medusa (also known as Gorgon).Perseus has killed her using aegis. By watching for her reflection in the shield he used the sword (also given by Athena) to chop off Medusa's head. After that Athena has picked aegis back and in memory of Medusa, Athena put Medusa's head in this shield.

Ancient greeks had used to sculpt or even drawn Gorgon heads at the front door of their houses in order to scare enemies, bad people, bad things and stuff. Maybe it could be the origin of the Medusa's myth, who knows...

Well, that is it, here we are using gorgon to scare debuggers! That's all folks!

;)

Back

`Aegis` from `Go`

I have decided to make an Aegis' Go bind because I am watching many applications related to information security being written mainly on Go, showing up during these years (2020). Who knows this bind can be useful for somebody somewhere over a concurrent multiplatform goroutine rainbow... Go is also my second best programming language so I have done it for fun, too. It was a good excuse for using Cgo.

Basically, you need to import aegis package from this repo:

import (
    "github.com/rafael-santiago/aegis/gopkg"
)

After you will define in your go.mod the following:

(...)
replace github.com/rafael-santiago/aegis/gopkg => github.com/rafael-santiago/aegis/gopkg/v2
(...)

You can also host it as a local package (no problem). Take a look how it can be done by taking a look at go.mod from Go samples (gopkg/samples).

This replace trick will allow you use Aegis' future releases without needing be noisy into your own related code. Renaming packages and all those MacGyver-like incantations, ready to go...

The usage of Aegis on Go is almost the same of its usage in C. Follow on reading if you are interested on it.

Back

`wait4debug` on `Go`

I am taking into consideration that you have already followed my notes about wait4debug C sample. Doing it on Go is quite straightforward, too. It is only about testing the attachment state by calling aegis.HasDebugger() oracle function, look:

//
// Copyright (c) 2020, Rafael Santiago
// All rights reserved.
//
// This source code is licensed under the BSD-style license found in the
// LICENSE file in the root directory of this source tree.
//
package main

import (
	"fmt"
	"github.com/rafael-santiago/aegis/gopkg"
	"os"
	"os/signal"
	"syscall"
	"time"
)

func main() {
	go func() {
		sigintWatchdog := make(chan os.Signal, 1)
		signal.Notify(sigintWatchdog, os.Interrupt)
		signal.Notify(sigintWatchdog, syscall.SIGINT|syscall.SIGTERM)
		<-sigintWatchdog
		fmt.Fprintf(os.Stdout, "\rinfo: ctrl + C received. Aborted.\n")
		os.Exit(1)
	}()
	fmt.Fprintf(os.Stdout, "info: Waiting for debug attachment (pid=%d)...\n",
		os.Getpid())
	for !aegis.HasDebugger() {
		time.Sleep(1 * time.Nanosecond)
	}
	fmt.Fprintf(os.Stdout, "\rinfo: Debug detected. Go home!\n")
}

The program will wait for a user's Ctrl + c interruption or for a debugger attaching. It is always important to sleep for some time interval, otherwise you will busy the main thread and cause starvation on other threads.

Back

What about a `Gopher Gorgon`?

Well, if you have some artistic inclination and want to make a Medusa-like gopher to put here I would be thankful haha!

Anyway, use Aegis Gorgon in Go is pretty straightforward, too. You just call aegis.SetGorgon(). Take a look:

//
// Copyright (c) 2020, Rafael Santiago
// All rights reserved.
//
// This source code is licensed under the BSD-style license found in the
// LICENSE file in the root directory of this source tree.
//
package main

import (
	"fmt"
	"github.com/rafael-santiago/aegis/gopkg"
	"os"
	"os/signal"
	"syscall"
	"time"
)

// INFO(Rafael): This function flags for aegis.SetGorgon() if it is time to stop watching and exit.
func shouldExit(exit interface{}) bool {
	exitChan := exit.(chan bool)
	var should bool = false
	timeout := time.Tick(1 * time.Nanosecond)
	select {
	case should = <-(exitChan):
	case <-timeout:
	}
	return should
}

func main() {
	exit := make(chan bool, 1)
	go func(exit chan<- bool) {
		sigintWatchdog := make(chan os.Signal, 1)
		signal.Notify(sigintWatchdog, os.Interrupt)
		signal.Notify(sigintWatchdog, syscall.SIGINT|syscall.SIGTERM)
		<-sigintWatchdog
		exit <- true
		fmt.Fprintf(os.Stdout,
			"\rinfo: ctrl + c received from the user. Exiting...\n")
	}(exit)
	fmt.Fprintf(os.Stdout, "info: process started (pid=%d)...\n", os.Getpid())
	// INFO(Rafael): Let's be less ambitious here. We will just pass our
	//               gracefully exit check function and its argument.
	//               OnDebugger and OnDebuggerArgs will be null, with this
	//               we will use the default Aegis' on debugger function
	//               that is only about a gross os.Exit(1) >:P
	go aegis.SetGorgon(shouldExit, exit, nil, nil)
	// INFO(Rafael): All your sensitive instructions not suitable for
	// eavesdroppers would go here. On some requirements you will need
	// to flush some buffers, files and stuff before exiting. For those
	// cases you would pass your custom OnDebugger and OnDebuggerArgs
	// to Aegis' Gorgon.
	<-exit
}

The program will run until detecting a debugger be attached or being asked for gracefully exiting through a ctrl + C.

Back

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Contents

How can I build it?

How should I easily clone `Aegis`?

Building it by using `Hefesto`

Poor man's build by using `make`

Making a distribution package

How should I build `Aegis` `Go` stuff?

Using `Aegis`

Debugging detection

Testing `wait4debug`

Debugging mitigation

Testing `setgorgon`

`Aegis` from `Go`

`wait4debug` on `Go`

What about a `Gopher Gorgon`?

Files

README.md

Latest commit

History

README.md

File metadata and controls

Contents

How can I build it?

How should I easily clone Aegis?

Building it by using Hefesto

Poor man's build by using make

Making a distribution package

How should I build Aegis Go stuff?

Using Aegis

Debugging detection

Testing wait4debug

Debugging mitigation

Testing setgorgon

Aegis from Go

wait4debug on Go

What about a Gopher Gorgon?

How should I easily clone `Aegis`?

Building it by using `Hefesto`

Poor man's build by using `make`

How should I build `Aegis` `Go` stuff?

Using `Aegis`

Testing `wait4debug`

Testing `setgorgon`

`Aegis` from `Go`

`wait4debug` on `Go`

What about a `Gopher Gorgon`?