Yandex Cloud IP Hunter is an open-source Python utility for automating public IPv4 allocation workflows in Yandex Cloud.

It reserves static public IPv4 addresses, checks them against user-defined exact IPs or CIDR ranges, cleans up unmatched resources, records state, writes operational logs, and can send Telegram notifications when a matching address is found.

The project was built for small infrastructure operators, DevOps engineers, and technically skilled users who need a transparent, auditable alternative to closed or paid “secret scripts” for Yandex Cloud IP allocation experiments.

This tool is intended for managing your own cloud resources. You are responsible for your Yandex Cloud quotas, billing, IAM permissions, and compliance with provider rules.

Public IPv4 allocation in cloud environments can be unpredictable. When a user needs an address from a specific range, manual allocation, checking, cleanup, and retrying becomes slow and error-prone.

IP Hunter automates that loop while keeping the process inspectable:

• configuration is stored locally in JSON;
• secrets are not committed to the repository;
• destructive cloud deletion requires explicit configuration and an explicit CLI flag;
• every run writes logs and state;
• dry-run mode is available for validation before real execution.

• Reserve public static IPv4 addresses in Yandex Cloud.
• Match allocated addresses against exact target_ips or target_cidrs.
• Delete unmatched addresses when configured to do so.
• Keep a matched address reserved after success.
• Support folder, cloud, and hybrid rotation modes.
• Switch cloud/folder context when allocation limits are reached.
• Store runtime state in state.json.
• Write logs to run.log.
• Send Telegram notifications on success.
• Provide dry-run and explicit deletion safeguards.
• Include a basic unittest suite for core logic.

yc_ip_hunter.py        Main CLI utility
config.example.json    Safe example configuration
test_yc_ip_hunter.py   Unit tests
.gitignore             Local secret/runtime file exclusions

• Python 3.9+
• Yandex Cloud account
• Yandex Cloud service account key or IAM token
• Billing and IAM permissions for the resources you want the tool to manage

Install Python dependencies:

python -m pip install PyJWT cryptography

Clone the repository and copy the example configuration:

Copy-Item .\config.example.json .\config.json

Place your service account key next to the script:

ip-hunter/
  yc_ip_hunter.py
  config.json
  sa-key.json

Start with a dry run:

python .\yc_ip_hunter.py --config .\config.json --dry-run

Run for real only after checking your configuration, quotas, and IAM permissions:

python .\yc_ip_hunter.py --config .\config.json --run --yes-delete-cloud

--yes-delete-cloud is required only for workflows that are allowed to delete clouds. This is a deliberate safety guard.

These files must remain local:

• config.json
• sa-key.json
• state.json
• run.log
• runner.*.log
• .env
• any *.key or *.pem files

They are already covered by .gitignore. If a service account key is ever pushed to a public repository, revoke it in Yandex Cloud immediately and create a new one.

Open console.yandex.cloud and collect the identifiers required by config.json.

This is the organization where clouds are created.

How to find it:

1. Click the organization name in the top-left area of the Yandex Cloud console.
2. Open Cloud Center or the organization page.
3. Find the organization identifier.
4. Copy it into organization_id.

Example:

"organization_id": "REPLACE_WITH_ORGANIZATION_ID"

This is required when new clouds need to be attached to billing.

How to find it:

1. Open Billing in the left menu.
2. Select the required billing account.
3. Find the billing account ID.
4. Copy it into billing_account_id.

"billing_account_id": "REPLACE_WITH_BILLING_ACCOUNT_ID"

If billing is not attached correctly, cloud creation may succeed while resource operations fail later.

This is the stable cloud that must not be deleted. The service account used by the script should live there.

How to find it:

1. Open the cloud that contains your service account.
2. Copy the cloud ID shown under the cloud name.
3. Paste it into service_cloud_id.

"service_cloud_id": "REPLACE_WITH_SERVICE_CLOUD_ID"

Do not delete this cloud. If it is deleted, the script loses its management identity.

Create a service account that will manage the required Yandex Cloud resources.

Basic flow:

1. Open the service cloud.
2. Select the default folder or the folder you use for infrastructure automation.
3. Open Identity and Access Management.
4. Open Service accounts.
5. Create a new service account, for example huntersa.

For folder mode, the service account needs permissions on the target cloud or folder where addresses are created.

For cloud and hybrid modes, the service account may also need permissions to:

• create clouds inside the organization;
• attach billing accounts;
• manage folders and VPC resources;
• delete resources created by the tool.

The simplest setup is to grant admin on the target resource scope. This is broad and should be reviewed before production use. A future improvement is to document a more minimal IAM role set.

This file is used for API authentication.

How to create it:

1. Open Identity and Access Management.
2. Open Service accounts.
3. Select your service account.
4. Create a new authorized key.
5. Download the JSON key.
6. Rename it to sa-key.json.
7. Place it next to the script.

Your config should contain:

"auth": {
  "service_account_key_file": "sa-key.json",
  "iam_token_env": "YC_IAM_TOKEN"
}

This is needed for rotation_mode: "folder".

How to find it:

1. Open the cloud where temporary folders should be created.
2. Copy the cloud ID under the cloud name.
3. Paste it into target_cloud_id.

"target_cloud_id": "REPLACE_WITH_TARGET_CLOUD_ID_FOR_FOLDER_MODE"

For hybrid or cloud mode, organization_id, billing_account_id, and service_cloud_id are the primary fields.

A practical hybrid-mode configuration:

{
  "dry_run": false,
  "rotation_mode": "hybrid",
  "organization_id": "YOUR_ORGANIZATION_ID",
  "billing_account_id": "YOUR_BILLING_ACCOUNT_ID",
  "service_cloud_id": "YOUR_SERVICE_CLOUD_ID",
  "auth": {
    "service_account_key_file": "sa-key.json",
    "iam_token_env": "YC_IAM_TOKEN"
  },
  "zone": "ru-central1-a",
  "zones": ["ru-central1-a"],
  "target_ips": [],
  "target_cidrs": [
    "84.201.188.0/23",
    "84.201.184.0/22",
    "84.201.128.0/18",
    "158.160.0.0/16"
  ],
  "max_iterations": 0,
  "max_addresses_per_cloud": 9,
  "max_parallel_clouds": 3,
  "allow_delete_cloud": true,
  "immediate_delete_cloud": true
}

target_cidrs contains the address ranges you want to match. The script stops only when an allocated address matches the targets you configured.

Creates temporary folders inside one existing cloud. This is the most conservative mode, but it can still hit limits at the cloud level.

Creates a new cloud, attaches billing, allocates addresses, and optionally deletes the cloud after an unmatched attempt. This is more aggressive and can hit organization-level cloud quotas.

Uses cloud/folder rotation logic to keep trying when allocation limits are reached. This is the main mode for advanced workflows.

Add this block to config.json:

"notifications": {
  "enabled": true,
  "telegram": {
    "enabled": true,
    "bot_token_env": "TELEGRAM_BOT_TOKEN",
    "chat_id": "YOUR_CHAT_ID"
  }
}

Store the bot token in an environment variable:

$env:TELEGRAM_BOT_TOKEN="123456:ABCDEF..."

Test notifications:

python .\yc_ip_hunter.py --config .\config.json --test-telegram

If the bot does not send a message, check:

• bot token;
• chat_id;
• whether you have sent at least one message to the bot;
• run.log.

python -m unittest .\test_yc_ip_hunter.py

The service account does not have enough permissions on the organization. Grant the required role in the organization access settings.

The service account does not have enough permissions on the target cloud, folder, or VPC resources. Grant the required role on the scope where allocation happens.

The organization has reached its cloud quota. Old clouds may stay in deletion for some time. The script performs cleanup before deletion, but provider-side quota release can still take time.

Run:

python .\yc_ip_hunter.py --config .\config.json --test-telegram

Then inspect run.log.

IP Hunter tries to be conservative around destructive actions:

• local secrets are ignored by Git;
• dry-run mode is available;
• cloud deletion requires both allow_delete_cloud: true in config and the --yes-delete-cloud CLI flag;
• the service account should live in a stable cloud that the script does not delete;
• state and logs are written locally for auditability.

Review the configuration before using the tool against real billing resources.

The project is usable as a practical automation utility and is currently maintained as a small open-source DevOps tool. Contributions that improve safety, tests, documentation, provider error handling, and minimal IAM guidance are welcome.

See ROADMAP.md and CONTRIBUTING.md.

This project is provided as-is. It is a utility for managing cloud resources under your control. You are responsible for your provider account, billing, quotas, IAM configuration, reserved addresses, deleted resources, and all operational consequences of running the tool.