Auditoría de un contrato Solidity: Episodio 7 - Documentación y elaboración de informes

Los contratos inteligentes pueden ser complejos, pero una documentación clara aporta transparencia. Mantener registros detallados puede simplificar los procesos de auditoría, eliminando las conjeturas a la hora de determinar su funcionamiento y funcionalidad. Hoy nos centraremos en la documentación y la elaboración de informes para los contratos inteligentes. Este es un buen punto de partida si quieres aprender sobre Solidity y cómo auditar contratos inteligentes. Este es uno de los artículos de una serie dedicada a la auditoría de contratos inteligentes en Solidity. La serie abordará las vulnerabilidades y los recursos que utilizan los auditores de contratos inteligentes.

Documentación y comentarios

La documentación y los comentarios tienen como objetivo mejorar la comprensión que tienen los auditores del código fuente. Las explicaciones claras sobre la funcionalidad constituyen la base de una documentación eficaz. Antes de la auditoría, es importante proporcionar descripciones exhaustivas del propósito y el comportamiento de cada componente significativo del contrato.

En los casos en que la lógica o los algoritmos implementados en el contrato sean complejos, es necesario incluir comentarios detallados. Estos comentarios deben desglosar la lógica paso a paso, facilitando a los auditores el seguimiento del flujo de ejecución del código. Además, pueden poner de relieve cualquier posible caso límite o consideración que haya influido en las decisiones de diseño.

La coherencia en el estilo de la documentación es fundamental para facilitar la lectura y la comprensión. La adopción de un formato estandarizado para los comentarios, como el uso de NatSpec u otros lenguajes de marcado, mejora la coherencia y facilita la generación automática de documentación y el análisis estático.

Actualizar la documentación a la vez que se realizan cambios en el código garantiza su pertinencia y precisión. Es fundamental revisar y corregir la documentación y los comentarios correspondientes a medida que el contrato evoluciona a través de actualizaciones o correcciones de errores. Esta práctica garantiza que la documentación refleje con precisión el estado actual del contrato, evitando así cualquier confusión.

¿Qué es un informe de auditoría?

Una vez finalizada la auditoría de un contrato inteligente, los auditores elaboran un informe en el que se detallan el alcance de la auditoría y sus conclusiones. El informe incluye, además, una evaluación de los niveles de gravedad y recomendaciones específicas de mejora. El resultado es un informe exhaustivo que contiene información útil.‍

Informes de auditoría

En las auditorías de contratos inteligentes se elaboran dos informes de auditoría:

Informe inicial de auditoría: Una vez finalizada la auditoría, los auditores elaboran un informe inicial. Este informe ofrece una breve descripción general de las vulnerabilidades detectadas en el código, así como de otras cuestiones que suscitan preocupación y recomendaciones sobre cómo el equipo de desarrollo del proyecto puede subsanarlas. Sirve de guía para corregir los problemas detectados y garantizar que el contrato inteligente esté completamente preparado para su implementación.

Publicación del informe final de auditoría: Consiste en la publicación de un informe final de auditoría exhaustivo. Este informe ofrece una visión detallada de todos los hallazgos, clasificando cada problema como resuelto o sin resolver. Por lo general, se comparte con el equipo de desarrollo del proyecto y se pone a disposición del público. Esto fomenta la transparencia y permite a los usuarios y a las partes interesadas tomar decisiones bien fundamentadas sobre la seguridad y la fiabilidad del protocolo.

Cómo redactar un buen informe de auditoría

Introducción: En esta sección se sientan las bases del informe de auditoría. Presenta al equipo de auditores, incluyendo sus credenciales y experiencia. Destaca la importancia del proceso de auditoría y su papel a la hora de mejorar la seguridad de los contratos inteligentes. Expone con claridad el objetivo de la auditoría y las metodologías empleadas en el análisis.

Descripción del proyecto: Ofrecer una visión general completa del proyecto objeto de la auditoría. Detallar la metodología de auditoría, describiendo las técnicas y herramientas utilizadas durante la evaluación. Especificar el tipo de contratos inteligentes que se han auditado, el lenguaje de programación en el que están escritos y su ecosistema. Incluir información como el enlace al repositorio del proyecto, el hash del commit de GitHub, las fuentes de documentación, los detalles de las pruebas unitarias, la página web del proyecto y las fechas de presentación y finalización de la auditoría.

Contratos incluidos en el alcance: Define el alcance de la auditoría enumerando los contratos inteligentes que se han auditado.

Resumen ejecutivo: Redacta un resumen conciso del proceso de auditoría, incluyendo detalles sobre los criterios de evaluación, las fechas de la auditoría y los auditores que han participado. Ofrece una visión general de las vulnerabilidades detectadas, clasificándolas según su nivel de gravedad. Destaca el número de incidencias detectadas, resueltas y reconocidas durante la auditoría.

Definiciones de gravedad: Defina los niveles de gravedad utilizados en el informe y explique con claridad qué significa cada nivel, para que a los lectores les resulte más fácil comprender las implicaciones de las vulnerabilidades identificadas.

Resumen de la auditoría: Esta sección debe incluir una puntuación de seguridad que refleje el estado general de seguridad de los contratos inteligentes. Se debe evaluar la calidad del código y de la documentación, resumiendo los puntos fuertes y débiles observados durante el análisis. Asimismo, debe ofrecer una visión general del estado de seguridad, que sirva de referencia rápida para los lectores.

Resultados de la auditoría: Analiza en profundidad las vulnerabilidades y los problemas identificados durante la auditoría. Ofrece una descripción detallada de cada vulnerabilidad, explicando su naturaleza, su impacto potencial y los pasos necesarios para reproducirla. Clasifica las vulnerabilidades según su nivel de gravedad, haciendo hincapié en los problemas críticos que requieren atención inmediata. Utiliza fragmentos de código y ejemplos para ilustrar las vulnerabilidades, lo que mejorará la claridad de tus explicaciones.

Recomendaciones: Para cada vulnerabilidad identificada, ofrece recomendaciones claras y prácticas para su resolución o mitigación. Detalla los pasos que deben seguir los desarrolladores para abordar los problemas de forma eficaz. Proporciona fragmentos de código, si procede, y buenas prácticas que puedan emplearse para mejorar la seguridad de los contratos inteligentes. Asegúrate de que las recomendaciones sean prácticas, viables y adaptadas al contexto del proyecto.

Aviso legal: En esta sección, se debe incluir un aviso legal en el que se describan las limitaciones de la auditoría y el alcance de las responsabilidades del equipo auditor. Aunque el objetivo de la auditoría es mejorar la seguridad, no puede garantizar una protección absoluta frente a todas las amenazas potenciales. Se debe destacar el carácter colaborativo de la seguridad, haciendo hincapié en la importancia de la vigilancia continua y de las medidas proactivas por parte del equipo de desarrollo.

En conclusión

Una documentación, unos comentarios y unos informes eficaces son esenciales para los contratos inteligentes. Ayudan a los desarrolladores a comprender y verificar las funciones de los contratos, facilitan la auditoría y la depuración, y permiten a las partes interesadas supervisar el rendimiento, lo que fomenta la confianza y la rendición de cuentas en el ecosistema de la cadena de bloques. Por eso, las auditorías de contratos inteligentes, los programas de recompensa por errores y las revisiones son fundamentales en todas las fases del desarrollo. Aumentan el número de personas que buscan vulnerabilidades y reducen la probabilidad de que se pasen por alto vulnerabilidades críticas.

‍

Cuídate.

‍

Únete a AuditOne como auditor: https://www.auditone.io/auditors

Reserva tu consulta gratuita sobre seguridad:

Google Calendar: https://calendar.app.google/Ai15eyQhiV5c1pBXA
Telegram: https://t.me/m_ndr

‍