{% extends "base.html" %} {% block title %}Settings{% endblock %} {% block content %}

← Back

Settings

Accounts

Add account

Snapshots, the IP list, the Visual page and suggestions always show the active account (selector in the top bar). Rules are shared and can be limited to one account.

{% for c in accounts %} {% set a = c.account %} {% else %} {% endfor %}
AccountRegionAuthCredentialsScheduled refresh
{{ c.label }} {% if active_account and a.id == active_account.id %}active{% endif %} {% if a.aws_account_id %}
AWS {{ a.aws_account_id }}
{% endif %} {% if a.identity_warning %}
Warning: {{ a.identity_warning }}
{% endif %}
{{ a.region }} {{ a.mode_label }}{% if a.auth_mode == 'profile' %} {{ a.profile }}{% endif %} {% if a.auth_mode == 'env' %}process environment {% elif a.auth_mode == 'profile' %}~/.aws profile {% else %} {% if a.access_key_id %}{{ a.access_key_id }}{% endif %} {% if a.memory_only %}memory only{% else %}encrypted{% endif %} {% if a.problem %}{{ a.problem }} {% elif a.auth_mode == 'temporary' %}{{ a.status }}{% endif %} {% endif %}
Edit
No accounts yet — add one.

Test calls sts:GetCallerIdentity and ec2:DescribeVpcs with the account's saved credentials. A scheduled refresh runs while IPLens is running, as a background job like the Refresh button (skipped while the account already has a job running).

Logging

Snapshot retention

Applied after every Refresh: snapshots older than the window are deleted, and older than the downsample threshold only the newest successful snapshot of each day is kept (Trends stay bounded). The latest successful snapshot of each account is always kept.

Discovery timeouts

A Refresh collects one resource type at a time (e.g. ec2:DescribeInstances). One that runs past its timeout is skipped and the others still run; once the overall limit is reached the remaining ones are skipped. The per-resource timeout applies to the optional resource types (instances, load balancers, managed-service names, tags, ...). VPCs, subnets and ENIs are required: they always get at least {{ required_timeout }} seconds (or the per-resource timeout if it is longer), and if one of them times out the Refresh fails. Defaults {{ default_resource_timeout }} seconds and 15 minutes; a change applies from the next Refresh.

Environments

A resource's environment comes from the Terraform repo root × environment that manages it; otherwise from the Ownership environment tag key below, then the first of these tag keys found on the resource, its subnet or its VPC (case-insensitive).

Ownership

Who manages each resource, first match wins: CloudFormation stack (cloudformation:ListStacks / ListStackResources) > IaC tag (the project / repo tag key) > Terraform state (only with the enrichment below) > CloudTrail creator (a CI role → "IaC (unknown repo)", anyone else → "manual") > unmanaged. Tags come from tag:GetResources. Only the values of these tag keys are kept; other tags are kept by key only (for the lists below).

{% for name, label in own_fields.items() %}
{% endfor %}

{% if seen_tag_keys %}{{ seen_tag_keys | length }} tag key(s) seen in the active account's latest snapshot. {% else %}No tag keys seen yet: Refresh the active account to fill these lists.{% endif %} A newly chosen key applies to every resource from the next Refresh.

Glob patterns (case-insensitive), comma or newline separated. A CloudTrail creator whose role / IAM user name matches one is a CI pipeline ("IaC (unknown repo)"); any other creator is "manual".

Opt-in, at most {{ cloudtrail_max }} resources per Refresh. CloudTrail event history only covers the last {{ cloudtrail_days }} days: older resources stay unmanaged. Only the creating role / user name is kept, never its ARN or session name.

Off by default. When on, mapped Terraform repos are also re-synced with every Refresh.

Terraform sync

Applies to terraform init and terraform show -json (default 120) of roots whose backend is not S3. Roots on an s3 backend never run terraform: their state object is read directly (read-only) with the mapped account's credentials, eight at a time; set values CI passes with -backend-config per root on the Terraform repo page. Two terraform root × environment pairs run at a time; providers are cached once in the IPLens data directory, and git module fetches fail instead of prompting for credentials.

Alerts

After each Refresh, every subnet of the account is checked against the thresholds below, and subnets whose alert state changed are posted to a webhook as one JSON message in the chosen webhook format. A subnet is only sent again when its state changes (including one "resolved" line when it clears), so repeated Refreshes do not repeat an alert. A failed send is logged, never fails the Refresh, and is retried after the next one. This webhook POST is the only outbound call IPLens makes besides AWS.

{% if alert.configured %}

Set: {{ alert.webhook_display }} encrypted — leave the box empty to keep it

{% elif alert.undecryptable %}
The stored webhook URL cannot be decrypted with the current secret key: set it again.
{% endif %}

Encrypted at rest like the account credentials, never logged and never shown again (only its host). https only.

Slack: {"text": "..."} for a Slack incoming webhook. Microsoft Teams: an Adaptive Card message for a Teams Workflows webhook ("When a Teams webhook request is received").

The forecast is a linear trend of the subnet's used IPs over the last {{ forecast_window }} days of snapshots (at least 5); it alerts when free IPs minus the demand at max scale reach 0 sooner than this. 0 turns a threshold off. Defaults 30 days and 10%.

Off by default: alerts name the account by its display name and each subnet by its Name tag and AZ.

{% macro snippet(id, text) -%}
{{ text }}
{%- endmacro %} {% set st = mcp_status %}

MCP server

Serves the read-only iplens mcp tools (subnet usage, headroom, IP lookup, snapshot diffs, fit check) over Streamable HTTP to editors and AI assistants. It runs as a separate process started by IPLens, reads the local database only and never calls AWS. Every request needs the bearer token below; requests from a browser page of another origin are rejected.

{% if not mcp.enabled %}
MCP is disabled: tick Enable MCP server below and save to start it. While disabled, iplens mcp (stdio and HTTP) refuses to run.
{% endif %} {% if mcp.allow_remote and mcp.remote %}
Remote access is enabled: the MCP server listens on {{ mcp.host }} and is reachable from other machines. The bearer token is its only protection and plain HTTP is not encrypted: use it only on a trusted network.
{% endif %}
Status{{ st.state }} {% if st.retries %}retry {{ st.retries }}/{{ st.max_retries }}{% endif %}
PID{{ st.pid or '—' }}
URL{{ st.url or mcp.url }}
Uptime{{ st.uptime_text or '—' }}
Last error{{ st.last_error or '—' }}
LogMCP server log {{ st.log_file }}
{% for action, label, cls in (('start', 'Start', ''), ('restart', 'Restart', 'secondary'), ('stop', 'Stop', 'danger')) %}
{% endfor %}

Settings

Local only (127.0.0.1) by default. The port must be free; saving restarts the server if it is running.

Token

{% if mcp_new_token %}
Copy the new token now: it is shown only once.
{{ snippet('mcp-token', mcp_new_token) }} {% elif mcp_has_token %}

A token is set encrypted — it is shown only when generated; regenerate it if you lost it.

{% else %}

No token yet: one is generated on the first start (or now).

{% endif %}

Encrypted at rest like the account credentials. The server process gets it in its environment, never on its command line.

Connect

VS Code — .vscode/mcp.json (VS Code asks for the token once and keeps it):

{{ snippet('mcp-vscode', mcp_vscode) }}

Claude Code — set {{ mcp_token_env }} to the token in your shell first (it is expanded there, so it stays out of the shell history):

{{ snippet('mcp-claude', mcp_claude) }}

stdio alternative — no HTTP server and no token: the client starts iplens mcp itself (on this machine).

{{ snippet('mcp-stdio-vscode', mcp_stdio.vscode) }} {{ snippet('mcp-stdio-claude', mcp_stdio.claude) }}

Terraform state

Load one or more .tfstate files or terraform show -json outputs, each as a named root. IPLens reads them locally and never modifies them. Only resource ids, addresses and types are kept (for {{ tf_types | join(', ') }}); attribute values, outputs and sensitive data are discarded while reading. The IP List, ENI pages and the Visual page then show which root manages each resource.

{% for r in tf_roots %} {% else %} {% endfor %}
RootSourceResource idsLoaded
{{ r.name }} {{ r.source }}{% if r.origin == 'repo' %} repo sync{% elif not r.source_path %} upload{% endif %} {{ r.resources }} {{ r.loaded_at | localtime }} {% if r.source_path %}
{% endif %}
No Terraform roots loaded.

Loading a root name again replaces it.

Terraform repos

Add a local Terraform repository. IPLens scans its .tf / .tfvars files (without running terraform) for roots, environments (env folders, *.tfvars, workspaces) and backends, and guesses each environment's AWS account. After you confirm the mapping, Sync (and every Refresh of a mapped account) runs only terraform init -input=false -lockfile=readonly, terraform workspace select and terraform show -json with the mapped account's credentials and TF_DATA_DIR in the IPLens data directory: the repository is never modified, and plan / apply / import are never run. Only resource ids, addresses and types are kept. See Ownership for sync status and drift. Terraform is an optional ownership source: enable the Terraform enrichment under Ownership to use it (and to re-sync mapped repos with every Refresh).

{% for p in tf_repos %} {% else %} {% endfor %}
RepositoryRootsRoot × envSynced pairsScanned
{{ p.path }} {{ p.roots }} {{ p.envs }} {{ p.confirmed }} {{ p.discovered_at | localtime }} Review mapping
No Terraform repos added.

IPLens only performs read-only AWS calls (Describe*/List*/Get*). Minimal IAM permissions: ec2:DescribeVpcs, ec2:DescribeSubnets, ec2:DescribeNetworkInterfaces, ec2:DescribeVpcEndpoints, lambda:ListFunctions, elasticloadbalancing:DescribeLoadBalancers. Optional: iam:ListAccountAliases (account name in the header); elasticloadbalancing:DescribeTargetGroups, elasticloadbalancing:DescribeTargetHealth, ec2:DescribeSecurityGroups (connections and security group names on the Visual page); elasticloadbalancing:DescribeTags, lambda:ListTags (load balancer and Lambda tags); tag:GetResources, cloudformation:ListStacks, cloudformation:ListStackResources (ownership) and, when enabled, cloudtrail:LookupEvents (creator of unowned resources). The Extended view's Kafka nodes need kafka:ListClustersV2 (Amazon MSK clusters) and lambda:ListEventSourceMappings; without them the source is skipped with a warning.
{% endblock %}