Automatisk registrering af IP-adresser – agent og netværksindsamler

Sådan virker det

Både agenten og indsamleren sender en rapport til ipmanager med POST /api/v1/agent/report over HTTPS med en API-nøgle i Authorization-headeren. ipmanager gør derefter følgende for hver adresse i rapporten:

Ny IP-adresse: oprettes med status »i brug«, og kilden markeres som agent eller scanning.
Kendt adresse: »sidst set« opdateres. Ændret værtsnavn eller MAC-adresse opdateres og logges i revisionsloggen.
Adresse, der var ledig eller offline: sættes til »i brug« igen.
Ingen ændring: kun »sidst set« opdateres, uden ny post i revisionsloggen.

Hvis organisationen har nået adressegrænsen, oprettes der ingen nye adresser. De tælles som limited i svaret, mens kendte adresser stadig opdateres.

	Agent	Indsamler
Kører på	Hver maskine, der skal rapportere	Én maskine i netværket
Finder	Maskinens egne adresser, værtsnavn og MAC	Alt, der svarer på ping, ARP-tabellen, omvendt DNS og DHCP-leases
Platform	Linux og macOS (shell), Windows (PowerShell)	Python 3 uden afhængigheder, typisk på Linux
Velegnet til	Servere og faste maskiner	Printere, IoT, AV-udstyr og alt, hvor du ikke kan installere noget

1. Opret en API-nøgle

Gå til Automatisk registrering og API i ipmanager, og opret en ny nøgle med adgangen agent. En agentnøgle kan kun sende rapporter – den kan ikke læse eller slette data. Nøglen vises kun én gang, så gem den et sikkert sted. Opret gerne én nøgle pr. lokation eller indsamler, så du kan tilbagekalde en enkelt nøgle uden at påvirke de andre.

2a. Agent på Linux og macOS

Download og test

curl -fsSo /usr/local/bin/ipm-agent.sh https://ipmanager.no/api/v1/agent/scripts/ipm-agent.sh
chmod 755 /usr/local/bin/ipm-agent.sh

# Test
IPM_TOKEN=ipm_xxxxxxxx sh /usr/local/bin/ipm-agent.sh

Læg nøglen i en fil, som kun root kan læse, i stedet for i crontab:

Gem nøglen

mkdir -p /etc/ipmanager
echo 'IPM_TOKEN=ipm_xxxxxxxx' > /etc/ipmanager/agent.env
chmod 600 /etc/ipmanager/agent.env

Med cron

# /etc/cron.d/ipmanager – rapportér hvert 15. minut
*/15 * * * * root . /etc/ipmanager/agent.env && IPM_TOKEN=$IPM_TOKEN sh /usr/local/bin/ipm-agent.sh >/dev/null 2>&1

Med systemd-timer

# /etc/systemd/system/ipm-agent.service
[Unit]
Description=ipmanager agent
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
EnvironmentFile=/etc/ipmanager/agent.env
ExecStart=/bin/sh /usr/local/bin/ipm-agent.sh

# /etc/systemd/system/ipm-agent.timer
[Unit]
Description=Run ipmanager agent every 15 minutes

[Timer]
OnBootSec=2min
OnUnitActiveSec=15min
RandomizedDelaySec=60

[Install]
WantedBy=timers.target

Aktivér timeren

systemctl daemon-reload
systemctl enable --now ipm-agent.timer

2b. Agent på Windows

Download og test (PowerShell som administrator)

New-Item -ItemType Directory -Force C:\ProgramData\ipmanager | Out-Null
Invoke-WebRequest https://ipmanager.no/api/v1/agent/scripts/ipm-agent.ps1 -OutFile C:\ProgramData\ipmanager\ipm-agent.ps1

# Test
$env:IPM_TOKEN = 'ipm_xxxxxxxx'
powershell -NoProfile -ExecutionPolicy Bypass -File C:\ProgramData\ipmanager\ipm-agent.ps1

Planlagt opgave hvert 15. minut

[Environment]::SetEnvironmentVariable('IPM_TOKEN', 'ipm_xxxxxxxx', 'Machine')

schtasks /Create /TN "ipmanager agent" /RU SYSTEM /SC MINUTE /MO 15 /F `
  /TR "powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\ProgramData\ipmanager\ipm-agent.ps1"

3. Indsamler i dit eget netværk

Indsamleren er ét Python 3-script uden afhængigheder. Den kører på én maskine i netværket – en server, en virtuel maskine eller en lille Linux-boks – og fungerer som mellemled: den ser netværket indefra og rapporterer ud til ipmanager.

Download og kør

curl -fsSO https://ipmanager.no/api/v1/agent/scripts/ipm-collector.py
python3 ipm-collector.py --help

# Scan to net, og tag ARP-tabellen med
python3 ipm-collector.py --token ipm_xxxxxxxx --arp 10.20.0.0/24 10.20.3.0/24

Indsamleren pinger adresserne i de net, du angiver, læser maskinens ARP-tabel for at finde MAC-adresser, slår omvendt DNS op for værtsnavne og kan læse leases fra dnsmasq og ISC DHCP. Se --help for alle muligheder.

Planlæg med cron

# /etc/cron.d/ipmanager-collector – hver time
0 * * * * root . /etc/ipmanager/agent.env && python3 /opt/ipmanager/ipm-collector.py --token "$IPM_TOKEN" --arp 10.20.0.0/16 >/dev/null 2>&1

ARP-tabellen indeholder kun maskiner i samme lag 2-net som indsamleren. For net bag en router får du IP og værtsnavn, men ikke MAC – medmindre du læser DHCP-leases eller kører en indsamler i hvert net.

4. DNS-tjek af interne navne

Offentlige IP-adresser tjekkes automatisk fra ipmanager.no mod offentlig DNS én gang i døgnet. Interne navne – som .local eller Active Directory-DNS – kan kun slås op indefra. Derfor kan indsamleren tjekke dem med --dns-check mod DNS-serveren i dit eget netværk.

Indsamleren henter de registrerede adresser med værtsnavn i de net, du angiver, slår PTR-posten op for hver IP og A/AAAA-posten for hvert navn og rapporterer resultatet. ipmanager sætter status OK, afvigelse eller mangler (PTR eller A/AAAA), og afvigelser vises også under Afvigelser. Med --no-scan springer indsamleren ping-scanningen over og tjekker kun DNS.

Kun DNS-tjek

IPM_TOKEN=ipm_xxxxxxxx python3 ipm-collector.py --dns-check --no-scan 10.20.0.0/16

Planlæg med cron

# /etc/cron.d/ipmanager-dns – hver nat kl. 03.15
15 3 * * * root . /etc/ipmanager/agent.env && IPM_TOKEN="$IPM_TOKEN" python3 /opt/ipmanager/ipm-collector.py --dns-check --no-scan 10.20.0.0/16 >/dev/null 2>&1

Bruger I korte værtsnavne, kan I angive et DNS-suffiks i ipmanager, så fil01 tjekkes som fil01.skole.local. Adresser uden værtsnavn får et forslag fra PTR-posten, som kan tages i brug med ét klik.

Afvigelser fra rapporterne

Rapporterne fra agenter og indsamler bruges også til at finde afvigelser: dubleret IP (to MAC-adresser på samme IP inden for få minutter), forkert MAC på en registreret IP (den registrerede MAC overskrives ikke), en kendt MAC på en anden IP, maskiner på adresser, der er registreret som ledige, reserverede eller udfasede, IP-adresser uden for registrerede subnet, faste adresser i DHCP-intervaller og ændrede værtsnavne. Afvigelserne løses automatisk, når forholdet forsvinder, og administratorerne får e-mail om nye kritiske afvigelser og advarsler.

Firewall og netværk

Agent og indsamler har kun brug for udgående TCP 443 til ipmanager.no. Der skal ikke åbnes noget indgående.
Indsamleren skal kunne sende ICMP echo (ping) til de net, den skal scanne. Maskiner med en værtsfirewall, der blokerer ping, bliver ikke fundet med ping, men kan dukke op via ARP eller DHCP.
Går udgående trafik via en proxy, kan scriptene bruge de almindelige proxyvariabler (HTTPS_PROXY).

Sikkerhed

Brug nøgler med adgangen agent. De kan kun rapportere, ikke læse eller slette.
Gem nøglen i en fil, som kun root eller SYSTEM kan læse, ikke i scripts, der tjekkes ind i versionsstyring.
Siden med API-nøgler viser, hvornår hver nøgle sidst blev brugt, og fra hvilken IP. Tilbagekald nøgler, der ikke bruges.
Scriptene er ren tekst. Læs dem igennem, før du kører dem.

Fejlfinding

Svar	Årsag
`401 invalid_token`	Forkert nøgle, eller nøglen er tilbagekaldt.
`403 insufficient_scope`	Nøglen har ikke adgangen agent.
`limited` > 0 i svaret	Organisationen har nået adressegrænsen. Nye adresser blev ikke oprettet.
Ingen nye adresser fra indsamleren	Tjek, at ping er tilladt, og at nettene er angivet i CIDR-notation.

Se API-dokumentationen for det præcise format på rapporten.