FilterLists

Background

FilterLists helps to protect your privacy and security when using the internet. It provides a comprehensive directory of subscription lists to block advertisements, malware, trackers, and other general annoyances. First, install one of the software tools that supports these lists. Then you can subscribe to a set of these lists inside of that software. If you need help or have a comment/question, start a Discussion.

Using a software firewall or adblocker has become a key tool in protecting one's privacy online. While the current business model of the "free" internet relies upon advertising revenue, publishers have become too flippant about tracking users without their consent. Advertising networks track users' browsing habits around the internet building lucrative profiles to exploit for targeted marketing or big data research. Until internet publishers develop more transparency or a new business model, we must continue to take the protection of our privacy into our hands.

Typical adblockers run as an extension in popular web browsers. As we browse the internet, they compare HTTP requests to their list of hosts and filters to selectively block advertisements, trackers, and malware. This filtering helps to protect the surfer's privacy, prevents malvertising attacks, and reduces bandwidth requirements. Thousands of contributors work hard to maintain these FilterLists for anyone to use. Locating and selecting these lists, however, has not historically been very easy. This project was launched in 2015 to solve that problem.

Services

Service	Description	More
Website	A React & TypeScript UI built with Ant Design.
Directory API	An ASP.NET Core API serving the core FilterList information.

Contributing

Adding or Updating Lists

To submit a new list or update data about an existing list, please submit a pull request to data in conjunction with the data model described here. Every JSON data change must be sorted with services/Directory/data/lint.sh and accompanied by an Entity Framework Core migration generated from services/Directory with dotnet ef migrations add <MigrationName> -p FilterLists.Directory.Infrastructure.Migrations -s FilterLists.Directory.Api.

If you assign one of these issues to GitHub Copilot cloud agent, add the directory-data label so the repository's agent instructions trigger the research-first workflow.

Alternatively, you can open a new issue providing information for all of the fields described in the data model.

In the future, we hope to have an easier form UI to submit updates. Follow this issue for any progress on that feature.

Note: Since the primary FilterLists.com site does not support Internet Explorer, we also have a separate page for tracking protection lists (TPL) here and viewed here.

Adding or Updating Rules

FilterLists does not maintain any of these lists. It serves only as a discovery tool to direct users to lists that they may want to use. If you want to request addition, modification, or removal of a rule from a list, you will need to contact the maintainers of that list directly. FilterLists provides a variety of ways you can get in contact with the maintainers to do so.

Building and Running Locally

FilterLists is build on the .NET Aspire stack. Install the .NET Aspire prerequisites before proceeding.

Directory API

Prepare Database Volume

So that the database does not need to be re-seeded on every startup, the SQL Server container is configured with a volume mount. Create a persistent password in order for this to be accessed by executing the command below in services/FilterLists.AppHost replacing <password> with a custom password:

dotnet user-secrets set Parameters:directorysqlserver-password <password>

Alternatively, remove the .WithDataVolume() configuration on the directoryDb resource in services/FilterLists.AppHost/Program.cs to re-seed the database on every startup.

MS Learn

Adding EF Core Migrations

Modify the database schema or seed data by adding an EF Core migration.

1. Install the EF Core tools.
2. Modify the QueryDbContext EF Core model or the seed data.
3. If you changed seed data under services/Directory/data, run ./lint.sh from that directory.
4. Execute the command below in the services/Directory directory replacing <MigrationName> with a meaningful name.

dotnet ef migrations add <MigrationName> -p FilterLists.Directory.Infrastructure.Migrations -s FilterLists.Directory.Api

Deploying to Production

Directory API

Create and Prepare SQL Server Database

Create an instance of SQL Server containing the users below.

Migrations user for applying EF Core migrations

USE [master];
GO

CREATE LOGIN [Migrations] WITH PASSWORD = 'my_password';
GO

USE [directorydb];
GO

CREATE USER [Migrations] FOR LOGIN [Migrations];
ALTER ROLE [db_ddladmin] ADD MEMBER [Migrations]; -- to apply migrations
ALTER ROLE [db_datareader] ADD MEMBER [Migrations]; -- to read from __EFMigrationsHistory
ALTER ROLE [db_datawriter] ADD MEMBER [Migrations]; -- to insert to __EFMigrationsHistory

ApiReadonly for API runtime reads

USE [master];
GO

CREATE LOGIN [ApiReadonly] WITH PASSWORD = 'my_password';
GO

USE [directorydb];
GO

CREATE USER [ApiReadonly] FOR LOGIN [ApiReadonly];
ALTER ROLE [db_datareader] ADD MEMBER [ApiReadonly];

Acknowledgements

• Imre Kristoffer Eilertsen @DandelionSprout : major contributor
• Raymond Hill @gorhill : uBlock Origin owner, advised on some technical aspects of FilterLists
• Andrey Meshkov @ameshkov : AdGuard CTO, advised on some technical aspects of FilterLists
• More contributors

Miscellany

Disclaimer

FilterLists does not condone subscribing to any particular FilterList or blocking any particular advertisement network. Make sure to financially support your favorite sites in some way if you choose to block their advertisements. FilterLists is also in no way officially affiliated with any of the software vendors or list maintainers referenced on this site.

Privacy

We respect your privacy. That is the whole point of this project. The only minor data we collect about visitors is what our infrastructure providers collect. These include:

• GitHub
• Azure
• Cloudflare