KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #deepseek-harness #typescript #ai-agent #codex #developer-tools #claude-code #windows #mcp #python #desktop-app

macof.py

★ 54 Open GitHub ↗

macof.py, a MAC address table overflow utility.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# macof.py

`macof.py` is a MAC address table overflow utility.

The traditional tool for MAC table overflow attacks is `macof` from the
[dsniff][] project.
However I was not satisfied with this tool.

In particular:

-	`macof` has no rate limit mechanism, it sends the packets as fast as the
	local CPU and the network adapter can support it.

This leaves no room for a proper interception of users data.

-	Half of the packets generated by `macof` [violates][protocol] the Ethernet
	protocol by having the multicast bit set on the sender's MAC address.

As a result, these packets are considered corrupted and silently dropped by
	the first encountered switch.

In other words, half of the packets generated by `macof` are generated
	for nothing.

-	`macof` constantly uses random MAC addresses for generated packets, meaning
	that a given source MAC address is rarely used more than once.

This means that switches' MAC table aging system will regularly clean the
	table from all malicious entries.
	Of course, the table will fill up again in a few seconds, but these seconds
	may be enough for the switch to learn a few more legitimate addresses.
	As a result data destined to these addresses won't be broad-casted anymore.

In other words the interception process is, here again, unreliable.

Most of these issues are probably due to the fact that this tool is now quite
old and seemingly unmaintained (last update in 2000).

I therefore decided to implement my own version, `macof.py`, compatible with
most options from dsniff's `macof`:

-	`macof.py` allows to tune the frame emission rate to minimize the impact on
	the attacker's host and the network resources as much as possible.

This offers a more reliable propagation of the forged MAC addresses
	throughout the switched network and a more efficient interception of
	broadcast data.

-	`macof.py` sends only valid frames, effectively updating switches MAC
	address tables.

-	`macof.py` first locally pre-generates a certain amount of Ethernet frames,
	each with a unique random source MAC address, and then replays this same
	set of frames in loop for all the attack duration.

This effectively simulate genuine devices activity, forcing the switches to
	regularly reset the associated aging-timers, keeping their MAC address
	table filled without interruption.

In addition `macof.py` functionalities can be easily included in larger Python
projects.

[dsniff]: https://www.monkey.org/~dugsong/dsniff/
	"dsniff project homepage"
[protocol]: https://www.whitewinterwolf.com/posts/2016/06/26/how-to-run-a-cam-table-overflow-attack-in-gns3/#using-the-right-tool
	"How to run a CAM table overflow attack in GNS3"

# Get it

*macof.py* is [freely available][github] (GPL v3).

Latest news on the project can be found on the [project's main page][news].

[github]: https://github.com/WhiteWinterWolf/macof.py
	"macof.py page on GitHub"
[news]: https://www.whitewinterwolf.com/tags/macofpy/
	"macof.py project homepage"

# Install it

`macof.py` and its accompanying man page can be installed system-wide using the
following commands:

install -m 755 -D -t /usr/local/bin ./macof.py
	mkdir -p /usr/local/share/man/man1
	gzip -c ./macof.py.1 >/usr/local/share/man/man1/macof.py.1.gz

# Documentation

-	[`macof.py` man page][man page] describes `macof.py` usage and options.
	It also provides advices and examples covering the most common use-cases.

-	You can also read this [practical use-case][lab], part of a series
	on network layer 2 exploitation and protection.

[man page]: https://www.whitewinterwolf.com/man/1/macof.py/
	"macof.py(1) man page"
[lab]: https://www.whitewinterwolf.com/posts/2017/10/25/mac-address-table-overflow/
	"MAC address table overflow"

# Report an issue

Please send bug reports to the [macof.py issues page][issues] on GitHub.

[issues]: http://github.com/WhiteWinterWolf/macof.py/issues
	"macof.py issues (GitHub)"

macof.py

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README