📋 Índice

• Quick Start
• Overview
• How It Works
• Prerequisites
• Detailed Installation
• Configuration
• Usage and Verification
• Troubleshooting
• Uninstalling
• License

🚀 Início Rápido

Passo 1: Obtenha seu token de API

Obtenha uma chave de API gratuita em tip.qfeeds.com.

Passo 2: Baixe os scripts```bash

git clone https://github.com/Q-Feeds/NFtables-IPtables-integration-script.git cd NFtables-IPtables-integration-script chmod +x qfeeds-installer.sh qfeeds-uninstaller.sh

### Step 3: Execute o instalador como root```bash
sudo ./qfeeds-installer.sh

O instalador irá:

1. Detectar automaticamente o seu backend de firewall (nftables ou iptables)
2. Solicitar o seu token de API, opções de bloqueio e lista de permissões opcional
3. Instalar todas as dependências, o script de atualização e a tarefa cron
4. Realizar a primeira sincronização completa imediatamente

Passo 4: Concluído

O seu servidor está agora protegido. A tarefa cron verifica atualizações a cada 20 minutos (configurável), e as chamadas reais à API só acontecem quando a sua licença permite.

📖 Visão Geral

Esta solução baixa periodicamente o feed de inteligência de ameaças mais recente do Q-Feeds e aplica-o como regras de firewall, permitindo-lhe:

• ✅ Bloquear conexões de entrada de IPs maliciosos conhecidos
• ✅ Bloquear conexões de saída para IPs maliciosos conhecidos
• ✅ Lista de permissões dos seus próprios IPs/CIDRs para nunca se bloquear
• ✅ Agendamento automático com base na sua licença Q-Feeds
• ✅ Atualizações incrementais via sincronização baseada em diferenças para uso mínimo de recursos

Porquê Esta Abordagem?

• ✅ Deteta backend automaticamente — funciona em nftables ou iptables+ipset sem seleção manual
• ✅ Rápido — carrega mais de 400 mil IPs em segundos usando conjuntos hash otimizados (nftables) ou ipset (iptables)
• ✅ Seguro — utiliza tabelas/conjuntos dedicados — nunca toca nas suas regras de firewall existentes
• ✅ Eficiente — atualizações baseadas em diferenças processam apenas alterações, não a lista completa
• ✅ Confiável — autocorreção: deteta um conjunto local vazio ou incompleto (ex.: após um reinício) e reconstrói-o, com recurso automático a sincronização completa se uma diferença falhar
• ✅ Flexível — escolha bloqueio de entrada/saída, lista de permissões opcional

🔧 Como Funciona

Deteção do Backend

O instalador deteta automaticamente qual o backend de firewall disponível:

O backend detetado é armazenado no ficheiro de configuração. Os scripts de atualização e desinstalação utilizam-no para executar os comandos de firewall corretos.

Arquitetura: Dois Tipos de Conjuntos

Ambos os backends utilizam a mesma estratégia de conjuntos divididos para máximo desempenho:

nftables backend:``` ┌─────────────────────────────────────────────────────────┐ │ table ip qfeeds │ │ │ │ ┌─────────────────────────┐ ┌───────────────────────┐ │ │ │ qfeeds_blacklist_v4 │ │ qfeeds_blacklist_v4 │ │ │ │ (hash set) │ │ _nets (interval set) │ │ │ │ │ │ │ │ │ │ Individual IPs │ │ CIDR ranges │ │ │ │ ~99% of entries │ │ ~1% of entries │ │ │ │ O(1) lookup & insert │ │ O(log n) lookup │ │ │ └─────────────────────────┘ └───────────────────────┘ │ │ │ │ ┌─────────────────────────┐ │ │ │ qfeeds_whitelist_v4 │ │ │ │ (interval set) │ │ │ │ Your allowed IPs/CIDRs │ │ │ └─────────────────────────┘ │ │ │ │ chain input-chain (hook input, priority 0, accept) │ │ → ip saddr @qfeeds_whitelist_v4 accept │ │ → ip saddr @qfeeds_blacklist_v4 drop │ │ → ip saddr @qfeeds_blacklist_v4_nets drop │ │ │ │ chain output-chain (if enabled) │ │ → ip daddr @qfeeds_whitelist_v4 accept │ │ → ip daddr @qfeeds_blacklist_v4 drop │ │ → ip daddr @qfeeds_blacklist_v4_nets drop │ └─────────────────────────────────────────────────────────┘

**iptables+ipset backend:**```
┌──────────────────────────────────────────────────────────┐
│  ipset sets                                              │
│                                                          │
│  ┌─────────────────────────┐  ┌────────────────────────┐ │
│  │ qfeeds_blacklist_v4     │  │ qfeeds_blacklist_v4    │ │
│  │ (hash:ip)               │  │ _nets (hash:net)       │ │
│  │ maxelem 1000000         │  │ maxelem 65536          │ │
│  │                         │  │                        │ │
│  │ Individual IPs          │  │ CIDR ranges            │ │
│  └─────────────────────────┘  └────────────────────────┘ │
│                                                          │
│  ┌─────────────────────────┐                             │
│  │ qfeeds_whitelist_v4     │                             │
│  │ (hash:net)              │                             │
│  └─────────────────────────┘                             │
│                                                          │
│  iptables: INPUT/OUTPUT jump to a dedicated chain        │
│  (jump rule tagged -m comment "qfeeds"):                 │
│                                                          │
│  chain QFEEDS_INPUT (rebuilt each run, in order):        │
│    -m set --match-set whitelist_v4 src -j ACCEPT         │
│    -m set --match-set blacklist_v4 src -j DROP           │
│    -m set --match-set blacklist_v4_nets src -j DROP      │
│    (QFEEDS_OUTPUT mirrors this with dst, if enabled)     │
└──────────────────────────────────────────────────────────┘

A mesma estrutura existe para IPv6 (tabela ip6 qfeeds ou ip6tables + family inet6 ipsets).

Por que dois tipos de conjuntos?

• Conjuntos hash armazenam IPs individuais com inserção e busca O(1) — carregar 400k+ IPs leva segundos
• Conjuntos de rede/intervalo são usados apenas para o pequeno número de faixas CIDR no feed
• Isso evita operações de mesclagem caras que atrasariam um único conjunto com centenas de milhares de entradas

Fluxo de Atualização```

┌──────────────────────────────────────────────────────┐ │ 1. Check license schedule (licenses.php API) │ │ → Skip run if not yet time for next update │ │ 2. Determine sync mode (full or diff) │ │ 3. Fetch IPv4 feed (ipv6=0) and IPv6 feed │ │ (ipv6=only) separately │ │ 4. Separate IPs from CIDRs in awk │ │ 5. Batch-load into hash set (IPs) and net/interval │ │ set (CIDRs) │ │ 6. Update whitelist sets from config │ │ 7. Persist rules │ └──────────────────────────────────────────────────────┘

### Full Sync vs Diff Sync

| Mode | When | What it does |
|------|------|-------------|
| **Full sync** | First run, forced update, after a diff failure, when the local set has lost its baseline (empty or much smaller than expected), or when the last sync is older than `FULL_SYNC_MAX_AGE` (default 24h) | Fetches and validates each feed first, then flushes and reloads the blacklist sets. The set is only flushed once valid data is in hand, so a failed fetch never leaves you unprotected |
| **Diff sync** | Subsequent runs (`malware_ip` feed only) with a healthy local set | Fetches only additions (`+`) and removals (`-`) since last pull |

The diff sync is **per API key** — the API tracks your last successful pull and only returns changes since then. If a diff fails, the script automatically falls back to a full sync.

> **Self-healing:** Diff updates only patch the existing set. If that set is ever lost or truncated — for example a reboot where the firewall rules were not persisted, a manual flush, or a previous partial sync — the updater detects the missing baseline (live element count is 0 or far below the last recorded count) and forces a full rebuild instead of diffing onto an empty set. As an extra safety net it also forces a periodic full sync (every 24h by default, via `FULL_SYNC_MAX_AGE`).

### License-Based Scheduling

The updater checks the Q-Feeds license API (`licenses.php`) before every run. If your license's `next_update` timestamp hasn't been reached yet, the script exits early without making unnecessary API calls. The cron job runs frequently (default: every 20 minutes), but actual updates only happen when your license allows.

---

## ✅ Prerequisites

Before installing, ensure you have:

- [x] **Linux server** with **nftables** or **iptables** (Debian, Ubuntu, CentOS, Fedora, Arch, Alpine)
- [x] **Root access** — the installer and updater must run as root
- [x] **Q-Feeds API Token** — get yours free at [tip.qfeeds.com](https://tip.qfeeds.com/)
- [x] **Internet access** — the server needs to reach `api.qfeeds.com`

The installer will automatically install required dependencies:
- **nftables backend**: `nftables`, `curl`, `jq`, `util-linux`
- **iptables backend**: `iptables`, `ipset`, `curl`, `jq`, `util-linux`

---

## 📝 Detailed Installation Guide

### 1. Get Your API Token

Visit [tip.qfeeds.com](https://tip.qfeeds.com/) to obtain your free Q-Feeds API token.

### 2. Download and Run```bash
git clone https://github.com/Q-Feeds/NFtables-IPtables-integration-script.git
cd NFtables-IPtables-integration-script
chmod +x qfeeds-installer.sh qfeeds-uninstaller.sh
sudo ./qfeeds-installer.sh

3. Perguntas do Instalador

O instalador fará as seguintes perguntas:

API Token (obrigatório)```

Enter your Q-Feeds API Token:

Seu token de [tip.qfeeds.com](https://tip.qfeeds.com/). O instalador se recusa a continuar se estiver vazio.

#### Tipo de Feed```
Enter feed type [default: malware_ip]:

O padrão é malware_ip. Só altere isto se a Q-Feeds lhe forneceu um tipo de feed diferente.

Limite de IP```

Enter the limit of IPs to fetch (leave empty for no limit):

Pressione Enter para sem limite (recomendado). Digite um número para limitar o tamanho do feed.

#### Bloqueio Direcional```
Block INCOMING connections from malicious IPs? [Y/n]:
Block OUTGOING connections to malicious IPs? [y/N]:

• Entrada (padrão: sim) — bloqueia o tráfego de IPs na lista negra para o seu servidor
• Saída (padrão: não) — bloqueia o tráfego do seu servidor para IPs na lista negra

Lista de permissões (opcional)```

Configure a whitelist of IPs/CIDRs that must NEVER be blocked? [y/N]: Enter IPv4 whitelist (comma-separated, e.g. 1.2.3.4,5.6.7.8): Enter IPv6 whitelist (comma-separated, e.g. 2001:db8::1):

Adicione seus IP(s) de gerenciamento aqui para garantir que você nunca seja bloqueado, mesmo que eles apareçam no feed. As regras de whitelist são sempre verificadas **antes** das regras de blacklist.

#### Cron Schedule```
Enter cron schedule (e.g., '*/20 * * * *') [default: */20 * * * *]:

Com que frequência o atualizador verifica novos dados. O padrão é a cada 20 minutos. O agendamento baseado em licença garante que a API seja chamada apenas quando sua licença permitir uma atualização.

Reexecutando o instalador com um crontab personalizado: Se uma entrada cron do Q-Feeds já existir, o instalador pergunta antes de tocá-la:

root@kitploit:~

An existing Q-Feeds cron entry was found in the current crontab.
Replace it with a fresh default entry? Choosing 'no' keeps your crontab unchanged [y/N]:

Responda no (o padrão) para manter seu crontab existente. Uma instalação limpa pela primeira vez não tem entrada existente e ignora este prompt. Para instalações desassistidas, defina QFEEDS_SKIP_CRON=1 para deixar o crontab intocado sem solicitação.

⚙️ Configuração

Todas as configurações são armazenadas em /etc/qfeeds/qfeeds_config.conf. Você pode editar este arquivo diretamente sem reexecutar o instalador. As alterações entram em vigor na próxima execução do cron.

Referência do Arquivo de Configuração

Arquivos Criados pelo Instalador

🎯 Uso e Verificação

Backend nftables```bash

Show the table structure and rules

nft list table ip qfeeds

Count loaded IPv4 IPs (individual addresses)

nft list set ip qfeeds qfeeds_blacklist_v4 | grep -oP '\d+.\d+.\d+.\d+' | wc -l

Show loaded CIDR ranges

nft list set ip qfeeds qfeeds_blacklist_v4_nets | head -20

Count loaded IPv6 addresses

nft list set ip6 qfeeds qfeeds_blacklist_v6 | wc -l

### iptables+ipset back-end```bash
# List all Q-Feeds ipsets and their sizes
ipset list -t | grep -A4 qfeeds

# Count loaded IPv4 IPs
ipset list qfeeds_blacklist_v4 | tail -n +9 | wc -l

# Show loaded CIDR ranges
ipset list qfeeds_blacklist_v4_nets | tail -n +9 | head -20

# Show the qfeeds jump rule in INPUT, then the dedicated chain's block rules
iptables -L INPUT -n --line-numbers | grep qfeeds
iptables -L QFEEDS_INPUT -n
ip6tables -L QFEEDS_INPUT -n

Comandos comuns (ambos os backends)```bash

Check the log (last 20 entries)

tail -20 /var/log/qfeeds_blocklist.log

Check for errors

grep -i "error" /var/log/qfeeds_blocklist.log

Normal run (respects license schedule)

sudo /usr/local/bin/update_qfeeds_blocklist.sh

Force a full sync (ignores schedule, reloads everything)

sudo QFEEDS_FORCE_UPDATE=1 /usr/local/bin/update_qfeeds_blocklist.sh

Verify cron is set up

sudo crontab -l | grep qfeeds

---

## 🔍 Solução de Problemas

### Geral

**Falha na instalação com "Unable to locate package"**
- O instalador detecta automaticamente a sua distribuição (Debian/Ubuntu, CentOS/RHEL, Fedora, Arch, Alpine). Se a deteção falhar, instale as dependências manualmente: `curl`, `jq`, `util-linux` (para `flock`), além de `nftables` ou `iptables`+`ipset`.

**Conjuntos estão vazios após a instalação**
- Verifique o registo: `tail -50 /var/log/qfeeds_blocklist.log`
- Verifique se o seu token de API está correto
- Tente uma atualização forçada: `sudo QFEEDS_FORCE_UPDATE=1 /usr/local/bin/update_qfeeds_blocklist.sh`

**"Ainda não é hora. Próxima atualização agendada para..."**
- O atualizador respeita a sua agenda de licença. Esta mensagem significa que o cron foi executado, mas a sua licença ainda não permite uma atualização. Isto é normal — a próxima execução do cron verificará novamente.
- O instalador Linux mantém um índice `licenses.php` em cache local e usa o `next_update` em cache como controlador de agenda. Após uma obtenção bem-sucedida, ele atualiza esse índice local para o próximo ciclo.

**As regras não persistem após reinicialização**
- Se `netfilter-persistent` estiver instalado, as regras são salvas automaticamente
- **nftables**: se `netfilter-persistent` estiver ausente, o atualizador agora escreve o conjunto completo de regras em `/etc/nftables.conf` automaticamente e ativa o serviço `nftables`; ainda pode salvar manualmente com `nft list ruleset > /etc/nftables.conf`
- **iptables**: o atualizador salva com `ipset save > /etc/ipset.conf` e `iptables-save`; também pode salvar manualmente
- Mesmo que a persistência falhe completamente, o atualizador se auto-recupera: na próxima execução, ele deteta o conjunto vazio após uma reinicialização e o reconstrói com uma sincronização completa

### Específico do nftables

**"Batch nft -f falhou. Recorrendo à execução por comando..."**
- Isto é normal, especialmente em contentores LXC onde o buffer netlink do kernel (`wmem_max`) está restrito. A alternativa de execução por comando funciona corretamente e é rápida (~10 segundos para mais de 400 mil IPs).

**Erro de sintaxe: "unexpected string"**
- Certifique-se de que está a executar uma versão recente do nftables. O script usa a sintaxe `ip saddr`/`ip daddr` que requer nftables 0.9+.

**"Error: Could not process rule: Message too long"**
- Este é o limite do buffer netlink, tipicamente em contentores LXC. O script recorre automaticamente à execução por comando. Se vir isto no registo juntamente com um carregamento bem-sucedido, está a funcionar como pretendido.

### Específico do iptables+ipset

**"ipset restore failed"**
- Verifique se `ipset` está instalado: `command -v ipset`
- Verifique o registo para erros específicos: `grep -i "error" /var/log/qfeeds_blocklist.log`
- Certifique-se de que o módulo ipset está carregado: `lsmod | grep ip_set`

**As regras iptables não aparecem**
- As regras de bloqueio residem nas cadeias dedicadas `QFEEDS_INPUT` / `QFEEDS_OUTPUT`; `INPUT`/`OUTPUT` apenas contêm um salto `-j QFEEDS_INPUT` marcado com o comentário `qfeeds`
- Verifique com: `iptables -L INPUT -n | grep qfeeds` (o salto) e `iptables -L QFEEDS_INPUT -n` (as regras de bloqueio)
- A regra de salto usa `-m comment --comment "qfeeds"` para identificação
- Certifique-se de que o módulo `xt_set` está carregado: `modprobe xt_set`

**"ipset create ... failed"**
- Em kernels muito antigos, os tipos `hash:ip` ou `hash:net` podem não estar disponíveis. Atualize o seu kernel ou instale o `ipset` a partir de um repositório mais recente.

---

## 🗑️ Desinstalação```bash
sudo ./qfeeds-uninstaller.sh

O desinstalador remove tudo com base no backend detectado:

nftables backend:

• Exclui as tabelas ip qfeeds e ip6 qfeeds (incluindo todas as chains, regras e sets)

iptables backend:

• Remove todas as regras iptables/ip6tables marcadas com o comentário qfeeds (incluindo as regras de salto)
• Limpa e exclui as chains QFEEDS_INPUT / QFEEDS_OUTPUT
• Destroi todos os conjuntos ipset (qfeeds_blacklist_v4, qfeeds_blacklist_v4_nets, qfeeds_whitelist_v4 e equivalentes IPv6)

Ambos os backends:

• Diretório de configuração (/etc/qfeeds/)
• Script de atualização (/usr/local/bin/update_qfeeds_blocklist.sh)
• Tarefa cron, arquivo de log e arquivo de bloqueio

Se o arquivo de configuração estiver ausente, o desinstalador tenta a limpeza para ambos os backends.

Nota: O desinstalador não remove pacotes do sistema (curl, jq, ipset, etc.) que foram instalados como dependências.

📄 Licença

Este projeto está licenciado sob a Apache License 2.0 - consulte o arquivo LICENSE para obter detalhes.

⚠️ Aviso Legal

Use por sua conta e risco.

Teste esses scripts em seu ambiente antes de implantá-los em produção. O autor não é responsável por quaisquer problemas ou danos que possam ocorrer com seu uso.

Assistência de IA: Partes deste projeto (código, correções e documentação) foram escritas com a ajuda de ferramentas de IA e posteriormente revisadas pelos mantenedores. Embora testemos e revisemos as alterações, revise os scripts por conta própria antes de executá-los e relate qualquer coisa que pareça estranha.