Backend¶
Python ≥ 3.11 (a imagem usa 3.12), FastAPI, SQLAlchemy 2 assíncrono + asyncpg, nats-py,
clickhouse-connect/chdb, numpy, httpx, asyncssh, pyVmomi, ldap3, cryptography/argon2, anthropic.
Todo o I/O é asyncio. Chamadas bloqueantes (chdb, ldap3, pyVmomi, smtplib, ansible-runner) rodam em
asyncio.to_thread.
quantix.common¶
| Módulo | Responsabilidade | Principais símbolos |
|---|---|---|
config.py |
variáveis de ambiente QV_* (pydantic-settings, .env) |
Settings, get_settings() (lru_cache), resolved_master_key(), resolved_jwt_secret() |
catalog.py |
catálogo canônico: tipos de objeto, relações, métricas (unidade, agregação, higher_is_worse, applies_to) |
ENTITY_TYPES, RELATION_KINDS, METRICS, Metric, catalog_dict() |
models.py |
modelo relacional (ver ER) | Tenant, User, Role, Device, Entity, Relation, Identifier, Finding, Health… |
db.py |
engine e sessões | get_engine(), session_scope() (serviços), get_session() (FastAPI), create_schema() |
tsdb.py |
ClickHouse: DDL (nó único/cluster), backends HTTP com failover e chdb, retenção | schema_statements(), MetricsStore, get_store(), pick_resolution() |
query.py |
consultas analíticas parametrizadas | MetricQuery (pydantic), QueryEngine.run(), modos timeseries/topn/latest/stat/heatmap/distribution |
topology.py |
BFS do grafo com política de expansão | neighborhood(session, root, depth, max_nodes), LAYER, FORWARD, BACKWARD |
bus.py |
NATS JetStream | connect(), ensure_streams(), consumer_config(), pack/unpack (msgpack) |
settings_registry.py |
variáveis da GUI | SettingDef, DEFS, REGISTRY, validate(), settings_cache |
crypto.py |
Fernet, Argon2, tokens | encrypt_json/decrypt_json, encrypt_str/decrypt_str, hash_password, new_token, hash_token |
ids.py |
IDs determinísticos e normalização | entity_id() (UUID5), normalize_wwn(), normalize_naa(), format_wwn() |
notify.py |
canais de alerta | send(channel, finding, settings), render_text() |
logging.py |
log JSON | setup_logging(service), JsonFormatter |
quantix.collector¶
service.py (CollectorService: config, reconciliação, laços alinhados, tarefas, heartbeat),
publisher.py (NatsPublisher com object store, HttpsPublisher), plugins/ (contrato em
base.py, utilitários em _util.py, registro em __init__.py::_MODULES). Ver
Coleta e Criando um plugin.
quantix.ingestor¶
service.py: metrics_loop (fetch de 256 mensagens; MetricsWriter valida o lote inteiro antes de
acumular; flush em 250 mil linhas ou 2 s; ack após o insert, nak(5 s) em falha, term para
mensagem inválida) e inventory_loop (uma mensagem por vez; baixa do object store, in_progress(),
apply_snapshot, ack; nak(30 s) em falha). inventory.py::apply_snapshot: COPY → diff
(config_changes) → merge de entidades → remoção lógica → identificadores → relações do coletor →
metadados do dispositivo, tudo em uma transação.
quantix.engine¶
| Módulo | Função pública | Ver |
|---|---|---|
service.py |
Engine.tick(), _with_lock() (advisory lock), main() |
Engine |
ratings.py |
run_ratings(), Thresholds.resolve(), level_for() |
ratings |
capacity_models.py |
lookup(), controller_utilization(), port_capacity_mbps(), expected_latency_factor() |
idem |
change_detection.py |
run_change_detection(), SERIES |
change detection |
forecast.py |
run_forecast(), theil_sen(), r2() |
previsão |
balance.py |
run_balance(), GROUPS |
balanceamento |
config_rules.py |
run_config_rules() |
regras |
correlator.py |
correlate(), RULES |
correlação |
findings.py |
F (achado), FindingSink.add/commit(), fmt_bytes, fmt_num |
ciclo de vida |
alerts.py |
dispatch() |
Alertas |
applications.py |
run_applications(), app_criticality() |
aplicações |
reports.py |
build_summary(), daily_summary() |
— |
Adicionar uma regra de achado: crie a função no módulo do job (ou um novo job em
Engine.tick), produza objetos F(rule, category, severity, title, detail, recommendation,
entity_id=…, key=…, magnitude=…, evidence=…), chame sink.add() e, ao final, await sink.commit().
O FindingSink(session, rules={...}, grace=N) resolve automaticamente apenas os achados das regras
informadas. Inclua a regra em Regras da engine e um teste em
tests/integration/test_pipeline.py.
quantix.ai¶
providers.py (AnthropicProvider, OpenAICompatibleProvider, make_provider) e assistant.py
(TOOLS, ToolRunner.t_<ferramenta>, Anonymizer, chat(), explain_finding()). Para adicionar
uma ferramenta: declare-a em TOOLS (nome, descrição, JSON Schema) e implemente t_<nome> em
ToolRunner, respeitando self._scope() (tenants) e self.anon (anonimização).
quantix.automation¶
worker.py: run_once() pega uma execução approved com FOR UPDATE SKIP LOCKED, monta inventário
e extravars (_context: qv_target, qv_device, qv_device_username/password, qv_finding,
itsm, parâmetros) e executa o playbook em diretório temporário isolado (ansible-runner, timeout
30 min, saída limitada a 200 mil caracteres). Para adicionar um runbook: crie
automation/playbooks/<arquivo>.yml e uma entrada em api/bootstrap.py::PLAYBOOKS (chave, nome,
descrição, risco, aprovação, tipos alvo, params_schema, que gera o formulário na GUI). Se precisar
de contexto especial, adicione-o em _context.
quantix.api¶
| Arquivo | Conteúdo |
|---|---|
main.py |
create_app(): middlewares (GZip, CORS fechado, cabeçalhos de segurança), handler de ValueError → 400, routers, lifespan (bootstrap + workers embutidos) |
bootstrap.py |
schema, papéis padrão, tenant padrão, admin, coletor padrão, runbooks, dashboards de sistema (system_dashboards.py) |
security.py |
PERMISSIONS, BUILTIN_ROLES, Principal, create_token/decode_token, current_principal, require(perm), current_collector |
ldap_auth.py |
authenticate(), test_directory(), map_roles() |
common.py |
audit(), entity_names(), page() |
routers/ |
auth, admin, devices (coleta e endpoints de máquina), data, insights, workspace (dashboards e aplicações), ops (alertas e automação), ai, system |
Adicionar um endpoint: escolha o router da área, declare o modelo pydantic de entrada,
proteja com Depends(require("<permissão>")), aplique o escopo de tenant
(p.tenant_ids() / p.tenant_slugs_for()), registre com audit() as alterações e devolva
page() em listas paginadas. Depois rode python docs/gen_api.py --refresh e adicione a descrição em
português em PT no gen_api.py.
quantix.tools¶
demo_seed.py (seed(days, arrays, hosts, step): dispositivos simulados + histórico) e admin.py
(reset_admin(username)).